home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
HamCall (April 1991)
/
HAMCALL CD-ROM (Buckmaster)(April 1991).BIN
/
telcom
/
telix
/
salt.doc
< prev
next >
Wrap
Text File
|
1988-10-09
|
221KB
|
6,770 lines
T E L I X
--------------------------------------------------------------------
SALT Programming Manual
Copyright (C) 1986,1987,1988 by Exis Inc.
ALL RIGHTS RESERVED.
Exis Inc.
Post Office Box 130
West Hill, Ont. M1E 4R4
Telix v3.00 - SALT Programming COPYRIGHT ii
COPYRIGHT NOTICE
Telix is Copyright (c) 1986, 1987, 1988 by Exis Inc.
This document is Copyright (c) 1988 by Exis Inc.
No parts of Telix or this document may be copied in part or in
whole, except as provided in the License included with Telix.
Disclaimer
Exis Inc. makes no warranty of any kind, either express or implied,
including but not limited to implied warranties of merchantability
and fitness for a particular purpose, with respect to this software
and accompanying documentation.
IN NO EVENT SHALL EXIS INC. BE LIABLE FOR ANY DAMAGES (INCLUDING
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF
BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE
USE OF OR INABILITY TO USE THIS PROGRAM, EVEN IF EXIS INC. HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Trademarks
Telix and SALT are trademarks of Exis Inc.
Telix v3.00 - SALT Programming Contents iii
C O N T E N T S
1 The Telix SALT Language..................................1
1.1 What Can be Accomplished With SALT?...................1
1.2 About This Manual.....................................1
1.3 Notation..............................................1
1.4 Creating SALT Programs................................1
2 Syntax...................................................3
2.1 Comments..............................................4
3 Program Structure........................................6
3.1 Variables.............................................6
3.2 Expressions and Operators.............................8
3.3 Functions............................................10
3.4 Statements...........................................11
3.4.1 The Expression statement...........................12
3.4.2 The If statement...................................12
3.4.3 The While statement................................14
3.4.4 The Do...While statement...........................15
3.4.5 The For statement..................................15
3.4.6 The Return statement...............................16
3.4.7 The Break statement................................17
3.4.8 The Continue statement.............................17
3.4.9 The Goto statement.................................18
4 Built-in Functions......................................20
4.1 Quick Listing of Functions by Type...................21
4.2 Complete Function Reference..........................23
5 System Variables.......................................111
6 Appendix A - ASCII Character Set.......................130
7 Appendix B - Extended Key Scan Codes...................131
8 Appendix C - Color Values..............................132
Telix v3.00 - SALT Programming Introduction 1
1. THE TELIX SALT LANGUAGE
Telix has a built-in programming language called SALT (Script
Application Language for Telix). SALT will allow you to perform al-
most any communications related applications with Telix. SALT looks
similar to the C language, however if you have used almost any
programming language (such as Pascal, BASIC, etc.), you should feel
quite at home with SALT. While SALT was designed to be easy to
learn, it is like most programming languages quite complete, so it
is recommended that you read this chapter thoroughly and study the
examples provided, as well as the sample SALT scripts included with
Telix.
1.1 What Can be Accomplished With SALT?
Like a program in any programming language, a SALT program (also
called a 'script') is typically used to perform a needed task or
function. The task can range from the very simple to the very com-
plicated. For example, a SALT script can be linked to a dialing di-
rectory entry, so that when you have established a connection to
that service, it automatically sends your i.d. and password to the
remote service. A much more complicated SALT script is used as the
basis for the Host Mode included with Telix.
1.2 About This Manual
This manual is basically a reference to the SALT programming lan-
guage. It is by no means a tutorial on programming in general. It is
assumed that the reader of this manual is at least familiar with
general programming concepts.
1.3 Notation
Throughout this manual, certain words in examples and in the text
will be surrounded by angle brackets and italicized, for example,
<expression>. These words are not to be taken as literal text. they
stand for something else, such as a word, a group of words, or even
several lines of text. What these italicized words stand for will be
explained as they come up.
1.4 Creating SALT Programs
A SALT script is basically a sequence of instructions for Telix to
follow, using a specific syntax. You may use any text editor to pro-
duce this script file, as long as its output is normal ASCII text
(this means that if you use your word processor, you must usually
explicitly tell it to write out the file using ASCII format and to
not embed any special codes in the file). You may give any name you
Telix v3.00 - SALT Programming Introduction 2
wish to a SALT source file, although we recommend that you always
use the extension .SLT for clarity.
Once you have written your script file and saved it to disk, it must
be compiled. The program CS.EXE included with Telix reads your
'source' script file, and compiles it to a form which Telix can
understand. The compiled script can then be loaded more quickly by
Telix, and is also usually smaller.
To compile a script source file, type
cs <pathname>
while at the DOS prompt and then press Enter (or Carriage Return).
The CS.EXE program must be in the current directory or on the DOS
PATH. <pathname> is the name of the file to compile, and may include
the drive and directory as well as the filename. The output file is
written to the same name except that the extension .SLC is used.
When the script compiler finds an error in your source file, it will
abort the compile process and give you the line number on which the
error occurred, as well as the type of error. The error should then
be fixed and the source re-compiled. This is repeated until the com-
piler detects no more errors in your source file.
The compiled script can then be run in Telix using several methods.
It may be run using the 'Run script' command, as a command-line op-
tion when running Telix from DOS, as a linked script to a dialing
directory entry, or from another script. The first three methods are
described in the Telix manual, while the last is described later in
this manual.
Telix v3.00 - SALT Programming Syntax 3
2. SYNTAX
Case is not important in command, function, and variable names. The
only time case matters is inside a string constant (e.g., "Hello" is
not the same string as "hello"). Whitespace (such as the space, the
tab, the Carriage Return, or the Line Feed character) is not impor-
tant. The script compiler does not care where you place items, so
that you may arrange the program as you see fit. For example,
if (value == 1)
prints("value is equal to 1!");
else
prints("values is not equal to 1.");
is equivalent to
if (value == 1) prints("value is equal to 1!");
else prints("value is not equal to 1");
or even to
if(value==1)prints("value is equal to 1!");else prints("value
is not equal to 1.");
The only time whitespace matters is when it would split up key-words
or function name, or in a string. For example, the key-word 'while'
must not be split up if it is to be recognized. The same applies to
other key-words or function names. As well, there must be space be-
tween the letters of a command and other letters. For example,
'while' is not the same as 'whileabc'. In the interest of clarity,
it is recommended that you try to make your code easy to understand,
by indenting where appropriate, and by using space effectively.
There is no reason, for example, to put more than one statement on a
line, even if it is perfectly legal. A good example of program style
can be found by looking at the sample scripts included with Telix.
A string constant is a sequence of ASCII characters enclosed in
quotes, for example, "Hello", "Good-bye", or "Telix". It is often
necessary for a string constant to include special characters that
can not easily be typed from the keyboard, or can not be easily dis-
played. This is done with something called the escape character,
which is the caret ('^') symbol. When the SALT compiler is reading a
string constant and comes to the '^' symbol, it replaces it with a
certain ASCII code based on the character following the ^. Transla-
tions are as follows:
^c 'c' is a letter. The Control representation of what-
ever letter 'c' is, is inserted into the text. There-
fore ^M represents Ctrl-M, ^j represents Ctrl-J, etc.
Whether the letter 'c' is upper or lower case is not
significant. Note that what is really happening here
is that 64 is being subtracted from the value of 'c',
Telix v3.00 - SALT Programming Syntax 4
so for example, the Escape character can be repre-
sented as ^[.
^^ An actual caret ('^') symbol is placed into the text.
^" An actual double quote symbol ('"') is placed into
the text. If a string must contain a double quote
symbol, this is how it has to be done. If the plain
'"' symbol were to be used, the compiler would think
that the string was terminated at that point. For ex-
ample, the string "He said, ^"Hello^"." is translated
to 'He said, "Hello".'.
^' An actual single quote symbol (''') is placed into
the text.
^nnn 'nnn' is up to 3 digits representing the ASCII value
of the character which should be placed into the
text. A maximum of three digits is read, or up to the
first non-digit character. For example, the compiler
would read in the string "S^65LT" and output the
string "SALT", since 65 is the ASCII value of 'A'.
Note that if nnn is less than 3 digits you may have
to pad it with one or two leading zeros if there are
digits immediately following it in the string, so
that the wrong value is not read in. For example the
string "^79 Park Avenue" would translate to "O Park
Avenue" since 79 is the ASCII value of 'O'. If you
actually wanted Ctrl-G (ASCII code 7) followed by "9
Park Avenue", you would use the string "^0079 Park
Avenue".
An integer constant is a sequence of digits representing an integer
value in the range -2147483648 to 2147483647. An integer constant
must start with a digit from 0 to 9 or the negative sign (-) fol-
lowed by a digit. The following are all valid integer constants:
10
-400067
999
An integer constant may also be entered in hexadecimal form (base
16, where each digit may be from '0' to '9' or 'a' to 'f', to repre-
sent 16 values). Hex values must be preceded by '0x' for the com-
piler to interpret them as such, and case is not important. The fol-
lowing are all valid integer constants enter in hexadecimal form:
0xff00
0Xa2
0x7D
0x1AbCdEf
2.1 CommentsA comment in a source file is text that does not affect
what the program does, and is meant purely for explaining or de-
scribing something. In a SALT source file, whenever the symbol // is
encountered on a line, all the characters from that point on until
the end of the line are considered to be a comment and are ignored.
For example:
Telix v3.00 - SALT Programming Syntax 5
prints("Hello"); // This line will print "Hello"
Telix v3.00 - SALT Programming Program Structure 6
3. PROGRAM STRUCTURE
A SALT script has the following format:
<global_variable_definition>
...
<global_variable_definition>
<function_definition>
<global_variable_definition>
...
<global_variable_definition>
<Function_definitions>
...
and so on. Basically a script file consists of definition of global
variables (variables which are available to any part of the script
file after which they are defined, and function definitions
(functions are lines of code clustered together in a group, so that
they can be called by a name). A script file does not have to have
any global variables or functions, but to run it must at least have
one function called 'main'. The following, for example, is a com-
plete script file:
main()
{
prints ("hello");
}
When compiled and run, this script would print the string "hello" to
the screen.
3.1 Variables
A variable is a location in memory where something is stored. The
contents of a variable can be changed by program code (hence the
name). In SALT, there are two types of variables, integer variables,
and string variables. The former holds an integer value (e.g.,
485624, or -627), while the latter holds a text string (e.g.
"Telix", or "SCRIPT"). Depending on where it is defined, a variable
is either global or local. If a variable is global, it means that it
can be used by any part of the script after the point where it is
defined. If a variable is local, it means that it can only be used
by the part of the script to which it is 'local', for example, the
function inside which it is defined. A variable name can be up to 31
Telix v3.00 - SALT Programming Program Structure 7
digits long, and may include the letters 'A' to 'Z' or 'a' to 'z',
the digits '0' to '9', or the underscore character (_). The name may
not start with a digit. For example, 'his_name2' and '_his_name2'
are legal as variable names, while '2his_name' is not.
An integer variable is defined in the form
int <varname>;
where <varname> is the name to be given to the variable. An al-
ternate definition is
int <varname1>, <varname2>, ..., <varnameN>;
which allows you to define more than one integer variable in one
statement. An original value can be assigned to the integer variable
by using the form
int <varname> = <int_const>;
where <int_const> is an integer constant. Similarly, an original
value can be assigned in the multiple definition above by placing
the assignment before the comma. Some examples are:
int maximum;
int start = 0;
int level, i, count = 20, loop;
A string variable is defined in the form
str <varname>[<max>];
where <varname> is the name to be given to the variable. <max> is
the maximum number of characters that the string can hold, and must
be in the range of 0 to 32767. An alternate definition is
str <varname>[<max>], <varname2>[<max>], ...,
<varnameN>[<max>];
which allows you to define more than one string variable in a state-
ment. An original value can be assigned to the string variable by
using the form
str <varname>[<max>] = <str_const>;
where <str_const> is a string constant. Similarly, an original value
can be assigned in the multiple definition above by placing the as-
signment before the comma. Some examples are:
str password[80];
str password[40] = "mypass", name[30];
The string length field may be left empty if an original value is
specified, in which case the length of the string variable is as-
sumed to be that of the assigned text, e.g.
Telix v3.00 - SALT Programming Program Structure 8
str name[] = "John";
If a variable is outside of a function, it is global. If it is de-
fined inside a function, it is local to that function and will only
be recognized there. If a variable defined inside a function uses
the same name as a global variable, any reference to that name while
in the function will access the local variable. After the function
has completed, the local variable is removed and a reference to that
name will access the global variable.
3.2 Expressions and Operators
An expression is a mixture of symbols which resolves to a value when
evaluated. In other words, an expression is basically a formula. An
expression can consist of constants, variables, function calls, and
operators. An expression can be very simple, or very complicated.
For example, some expressions are:
10 + 3 - 5
9 * 7 / 63 - 30
result = 10 * max(a, b)
month >= 10
200
command == "bye"
prints("Hello")
In an expression, the data being acted upon are constants, vari-
ables, and functions calls, while the operators (+, *, etc.) are the
symbols that do things with the data. There are many different oper-
ators, of which there are two basic types. Binary operators (such as
+, *, /) perform a calculation on the expression on either side of
them. Unary operators appear before a single expression and work on
that. The following table lists the operators available in SALT:
Symbol (Un/Bin)ary What it is/does
- unary Arithmetic negation
! unary Logical NOT
not unary Logical NOT (alternate)
* binary Multiplication
/ binary Division
% binary Remainder (Mod)
+ binary Addition
- binary Subtraction
< binary Less than
> binary Grater than
<= binary Less than or equal to
>= binary Greater than or equal to
== binary Equality
!= binary Inequality
& binary Bitwise AND
| binary Bitwise OR
^ binary Bitwise Exclusive OR
&& binary Logical AND
and binary Logical AND (alternate)
Telix v3.00 - SALT Programming Program Structure 9
|| binary Logical OR
or binary Logical OR (alternate)
= binary Assignment
Note that the hyphen symbol can be either an arithmetic negation or
a subtraction depending on its use. Note that '!' is equivalent to
'not', '&&' is equivalent to 'and', and '||' is equivalent to 'or'.
The first form is preferred as you do not have to leave whitespace
around it for the compiler to recognize it, but beginners may have
an easier time remembering the second form. Also, do not confuse the
'=' (assignment operator) with the '==' (equality operator). The
former is used to assign a value to a variable, while the latter is
used to compare two values. Assuming you have the two expressions,
<expr1> and <expr2>, <expr1> = <expr2> would assign one to the
other, while <expr1> == <expr2> would test the two to see if they
are equal. For example
num = 10
would assign the value 10 to the variable called 'num', while
num == 10
would resolve to a value of non-zero (TRUE) if num was equal to 10,
and 0 (FALSE) if num was not equal to 10. There is also a difference
between the Logical operators and the Bitwise operators. The Logical
operators (such as and, &&, or, ||, etc), work with TRUE or FALSE
values and result in a TRUE or FALSE value, while the Bitwise opera-
tors (&, |, ^) work with the actual bits of the data they are han-
dling. The Bitwise operators almost never have to be used in a Telix
script, unless it is needed to get at the actual bits in a data
byte.
Every operator resolves to a value, which is the result of the
operation performed (e.g, 10 * 7 would resolve to 70). The condi-
tional or equality operators such as ==, >, <=, etc., resolve to a
0 (FALSE)) or non-zero (TRUE) value based on the results of the ex-
pression. Even the assignment operator = resolves to a value. The
result of the expression
num = 10
would be 10.
All the operators have something called precedence, which is their
importance, and determines the order in which they are evaluated.
For example, 7 + 3 * 9 is equal to 34, because 3 * 9 is evaluated
first, and then added to 7 (* has a higher precedence than +). All
the operators are listed below in order of decreasing precedence.
All the operators on the same line have the same precedence, and are
resolved in the order that they are encountered.
Telix v3.00 - SALT Programming Program Structure 10
- !
* / %
+ -
< > <= >=
== !=
&
|
and &&
or ||
=
If a certain evaluation order is required that does not follow these
rules of precedence, parentheses may be used. Thus, 99 + 1 * 10
equals 109, while (99 + 1) * 10 equals 1000.
If you are writing an expression of any sort, and are not sure of
the exact precedence of the operators you are using, use paren-
theses!
3.3 Functions
A function is a way of grouping together some lines of code. A Telix
script consists of one or more functions. There are quite a few
advantages to having functions:
One function can be called from another, to do a certain task.
The calling function does not have to know anything about the
called function other than what it does. This allows a script
to be split up into modular units, and makes code writing and
debugging easier.
As mentioned above, what a function does it private. This means
that data variables defined in a function are local to that
function, and therefore you do not have to worry about another
part of the script unintentionally modifying them.
A library of functions can thus be built. Later, you do not
have to re-write old code.
Functions are defined in the following format:
<funcname>(<arg1>, <arg2>, ..., <argN>)
{
<variable_def>
...
<variable_def>
<statement>
...
<statement>
}
Telix v3.00 - SALT Programming Program Structure 11
<funcname> is the name of the function. It follows the same rules of
other identifiers in SALT. There can only be one function that uses
a given name, however.
<arg1> through <argN> are the declarations of the arguments
(parameters) that have been passed to the function by its caller
(sometimes, to accomplish its task, a function needs to have some
values passed to it). Each argument is defined in the form <type>
<name> where <type> is 'int' or 'str', and <name> is the name it
should be called by. At present, a function is not allowed to have
more than 12 values passed to it.
<variable_def> is a variable definition, as described in the above
section on that topic. Any number of variables may be declared at
this part of the function. All such variables will be local vari-
ables and available only to this function.
<statement> is an actual line of code. There may be as many lines of
statements in the function as needed. The format of a statement is
described below. First though, here is an example of a complete
function:
max ( int a, int b )
{
int result;
if (a > b)
result = a;
else
result = b;
return result;
}
This function returns the larger (maximum) of the two values passed
to it. It could have been written much more simply (without the use
of the variable), but was written this way so that all the function
elements would be there.
3.4 Statements
A statement is the basic element of code. A statement ALWAYS ends
with a semicolon character (;). In any location where a statement is
acceptable, you may use a group of statements, by enclosing them all
in curly braces (more on this below). There are many types of state-
ments, including: expression, if, while, do...while, for, return,
break, continue, and goto statements. Each type has several differ-
ent parts.
Telix v3.00 - SALT Programming Program Structure 12
3.4.1 The Expression statement
The 'expression' statement is the simplest and most common type of
statement. Its format is
<expression>;
where <expression> is any expression. Example are:
result = 20;
password = "Beef";
pause(20);
num = 20 * max(a, b);
Do not forget the semicolon character at the end of the statement.
If you do, the compiler will think that the next statement is part
of the current one, and will report some unexpected error.
3.4.2 The If statement
An 'if' statement is used when a statement or group of statements
should be evaluated only if a condition is true. The format for an
'if' statement is as follows:
if (<expression>)
<statement>
<statement> is any statement as described above and below (that is,
an expression, if, while, do...while, for, return, break, or con-
tinue statement), and will only be executed if <expression> eval-
uates to non-zero. By using curly braces around them, a whole group
of statements may be conditionally evaluated. Some examples are:
if (result == -1)
prints("ERROR!");
if (num_tries > maximum)
return 0;
if (month > 10 && day < 20)
{
clear();
prints("In range.");
return 1;
}
An alternate form of the if statement is:
if (<expression>)
<statement1>
else
<statement2>
Telix v3.00 - SALT Programming Program Structure 13
In this case, if <expression> evaluates to non-zero (TRUE),
<statement1> is executed, otherwise <statement2> is executed. Again,
multiple statements may be used instead by grouping them in curly
braces. Some examples are:
if (stat == -1)
prints("Error status returned.");
else
prints("Function finished without problems.");
if (level < 10)
{
alarm(1);
prints("Warning!");
}
else
prints("Everything's ok.");
Since the statement to be executed conditionally can be of any type,
that means that any number of if statement can be nested if needed.
For example:
if (num < 10)
if (!error)
if (read != 0)
return 1;
This also means that something like the following is legal:
if (value == 10)
do_this();
else if (value == 100)
do_that();
else if (value == 1000)
do_something_else();
else
do_whatever();
What is really happening here is that each if statement is being
nested after the else portion of the previous one. The above example
could also be written as:
if (value == 10)
do_this();
else
if (value == 100)
do_that();
else
if (value == 1000)
do_something_else();
else
do_whatever();
Any amount of nesting is theoretically legal, but the compiler does
have a limit due to memory constraints.
Telix v3.00 - SALT Programming Program Structure 14
While you may write the code in any way which suits you, it is
recommended that you use indenting, for clarity. Indenting your code
at the proper places makes it a lot easier to read.
A very common error to watch out for is accidentally placing a semi-
colon after the parenthesis ending the expression. For example, if
the following is run:
if (num == 10);
prints("Num is equal to 10);
the string would always be printed, no matter what num was equal to.
This is because the semicolon after the parenthesis ending the
expression signifies the end of the statement. In the above case, it
would just be a null (empty) statement.
3.4.3 The While statement
The while statement is used to loop continuously while a certain
condition is true. It has the form
while (<expression>)
<statement>
<statement> would continue to be repeated over and over while
<expression> evaluated to non-zero (TRUE). Note that if the ex-
pression evaluates to 0 (FALSE) from the beginning, the statement
will never be executed. Again, multiple statements may be used by
surrounding them in curly braces. A few examples are:
while (stat != -1)
stat = myfunc();
while (num < 100)
{
printn(num);
prints("");
num = num + 1;
}
while (1)
{
if (func1())
return 0;
func2();
}
Again, be careful to not place a semicolon after the parenthesis
ending the expression.
Telix v3.00 - SALT Programming Program Structure 15
3.4.4 The Do...While statement
The do...while statement is similar to the while statement and has
the form:
do
<statement>
while (<expression>);
<statement> will be executed at least once and will continue to be
executed repeatedly until the expression becomes 0 (FALSE). A few
examples are:
do
stat = func1();
while (stat != -1);
do
{
prints("hello");
num = num + 1;
}
while (num < 100);
3.4.5 The For statement
The for statement is used to loop continuously while a certain
condition is true. The advantages over the while statement is that a
count variable can be initialized and incremented quite easily. The
for statement has the form:
for (<expression1>; <expression2>; <expression3>)
<statement>
The first expression is the one that should initialize the count
variable. For example, if you wanted to count from 1 to 100, and
were keeping the count in a variable called 'num', the first ex-
pression would be 'num = 1'. The second expression is the condi-
tional test. As long as it evaluates to non-zero (TRUE), the state-
ment will be executed. Following the above example, this expression
would be 'num < 100'. The third expression is the one that is used
to increment the count variable. For the above example, it would
therefore be 'num = num + 1'. This for statement differs in format
from that in most other languages, but doing it this way is actually
gives the programmer a lot of power and flexibility. Note that any
of the expressions can be left empty, in which case they evaluate to
non-zero (TRUE). Some examples are:
for (count = 0; count < 100; count = count + 1)
{
printn(count);
prints("");
}
Telix v3.00 - SALT Programming Program Structure 16
for (c = 1000; c > 0; c = c - 1)
do_this(c);
The following would execute an infinite loop:
for (;;)
prints("Hello!");
Note that there is really no restriction on what the expressions
are. For example, the following is quite legal:
for (c = num = 0; c < 100 && stat != -1; c = c + 1)
{
stat = func(num);
num = func2();
}
The statements would only be executed if c was smaller than 100 and
stat didn't equal -1.
3.4.6 The Return statement
At some time, every function must be exited. If the end of the func-
tion is reached, control will automatically return to the calling
function. Very often however, it is necessary to leave a function
somewhere while only halfway through it, perhaps based on a condi-
tional test. As well, it is often necessary that a function returns
a value to the caller. The format of the return statement is:
return <expression>;
If the return statement is encountered anywhere in the function,
control immediately returns to the function that called this func-
tion. The expression is the value that should be returned. If no ex-
pression is supplied, a dummy value is returned. The expression
should match they type of value that the caller of this function is
expecting. That is, if an 'int' type is expected, the expression
should resolve to an integer value. If a 'str' type is expected, the
expression should resolve to a string value. Due to memory con-
straints, a local string variable may NOT be returned from a func-
tion. Some examples are:
return;
return 1;
return level;
return (sum + 25);
return "hello";
return (func() + 20);
Notice that when a complex expression is returned it is usually sur-
rounded by parentheses. This is done only for clarity and is not
necessary. Also, it should be clear that what is returned is not the
expression but what it evaluates to.
Telix v3.00 - SALT Programming Program Structure 17
3.4.7 The Break statement
Often while using a looping statement (while, do...while, for), it
is necessary to break out of (exit) the loop. The break statement
serves this purpose. When the break statement is encountered, execu-
tion of the smallest while, do...while, or for loop is terminated,
and execution continues immediately after the terminated loop state-
ment. It is an error for a break statement to appear outside of a
loop. The format of the break statement is:
break;
For example, assuming you had the following code:
int num = 0;
while (1)
{
num = num + 1;
if (num > 100)
break;
}
prints("Done");
Ordinarily, since there will always be a non-zero (TRUE) value in
the conditional part of this while statement, it would execute for-
ever. However, when the 'num' variable is > 100, the break statement
is executed to exit from the loop, at which point the next statement
would be executed (the function call to prints).
3.4.8 The Continue statement
The continue statement is used within a loop (while, do...while, or
for statement). The continue statement has the form:
continue;
It is illegal for a continue statement to appear outside of a loop
body. When a continue statement is encountered, program control is
immediately transferred to the end of the body of the innermost en-
closing while, do...while, or for statement. The effect in a while
or do...while statement is that the condition part of the while or
do...while statement is evaluated, and the next iteration of the
loop occurs. For example:
num = 0;
while (num < 100000)
{
num = num + 1;
if (num > 100)
continue;
prints("Hello");
}
Telix v3.00 - SALT Programming Program Structure 18
The effect of the continue statement in the above loop would be that
'Hello' would only be printed while 'num' was smaller or equal to
100, as the continue statement is executed when num is bigger than
100, which causes the rest of the loop body to be skipped. An ex-
ample for statement would be:
for (num = 0; num < 100000; num = num + 1)
{
if (num > 100)
continue;
prints("Hello");
}
The effect in this case would be the same. While 'num' is smaller or
equal to 100, the entire loop body executes. If 'num' is greater
than 100 however, the continue statement is executed. This causes
the rest of the loop body to be skipped, so the 'Hello' is then not
printed.
3.4.9 The Goto statement
The goto statement is used to branch (jump) from one place to an-
other, within a function. The use of goto statements is considered
bad style. They can make code very hard to understand, and are in
fact almost never necessary. For example, Telix is written mainly in
the C language, which has a goto statement, yet except for a few
pieces of pre-written code, the goto statement was never used nor
needed. On the other hand, used very sparingly and properly, it can
sometimes make some code clearer and perhaps faster. The goto state-
ment consists of two parts, the 'label' or marker, which is where
execution will jump to, and the actual goto itself. A label is de-
fined in the form
<identifier>:
where <identifier> follows the same rules as for variable names.
Note that a colon follows the name, not a semicolon. The colon char-
acter must immediately follow the label name, with no intervening
spaces. A label does not have to be on a line by itself, and is not
considered a statement by itself. The goto takes the form
goto <label>;
where <label> is a label elsewhere in the function defined as de-
scribed above. Execution of the script will immediately continue
following the label.
An example is:
start:
prints("Hello");
goto start;
Telix v3.00 - SALT Programming Program Structure 19
This would print the word "hello" over and over, forever. There is
no restriction on the placement of a label, so the above can be
written as:
start: prints("Hello");
goto start;
As mentioned above, there are usually better ways than using a goto
statement. For example:
int i = 0;
do
i = i + 1;
while (i < 100);
is clearer than the equivalent:
int i = 0;
loop:
i = i + 1;
if (i < 100)
goto loop;
One good use of a goto statement is to get out of a deeply nested
while statements, without having to do a lot of extra checking.
Telix v3.00 - SALT Programming Built-in Functions 20
4. BUILT-IN FUNCTIONS
Telix has quite a large number of built-in functions. These func-
tions are called just as you would call your own SALT functions.
Each function does a certain task (print something to the screen,
manipulate strings, access disk files, etc.). Each function is
called with parameters in a certain format and returns an integer or
string value (the return value does not have to be used and is often
a dummy variable).
The following pages contain a quick listing of the functions by type
followed by a complete description of each function, in alphabetical
order. The complete reference contains for each function, a summary
of the calling format, a description of what it does, and the return
value of the function are all given. An example of actual usage of
the function is often be given. So that you may find related func-
tions, each function description has a 'See Also' section, which
lists related functions.
Telix v3.00 - SALT Programming Built-in Functions 21
4.1 Quick Listing of Functions by Type
Video Operations
box, cursor_onoff, clear_scr, getx, gety, gotoxy, printc, printn,
prints, printsc, pstra, pstraxy, scroll, status_wind, update_term
String Handling
copychrs, copystr, delchrs, gets, getsxy, inschrs, itos, setchr,
setchrs, stoi, strcat, strchr, strcmpi, strlen, strlower, strmaxlen,
strpos, strposi, strupper, subchr, subchrs, substr
Character Handling
isascii, isalnum, isalpha, iscntrl, isdigit, islower, isupper,
tolower, toupper
Comm Port Operations
carrier, cinp_cnt, cgetc, cgetct, cputc, cputs, cputs_tr, flushbuf,
get_baud, get_datab, get_parity, get_port, get_stopb, hangup,
set_cparams, set_port
File and File I/O Operations
fclearerr, fclose, ferror, feof, fflush, fgetc, fgets, fileattr,
filefind, filesize, filetime, fnstrip, fopen, fputc, fputs, fread,
fseek, ftell, fwrite
Keyboard Operations
inkey, inkeyw, keyget, keyload, keysave, keyset
Date/Time and Timer Operations
curtime, date, tsec, tday, thour, time, time_up, timer_free,
timer_restart, timer_start, timer_total, tmin, tmonth, tyear
File Transfers, Capture, Printer, and Usage Log
capture, printer, receive, send, transtab, usagelog, ustamp
Script Management
call, calld, delay_scr, is_loaded, load_scr, unload_scr
Input String Matching
track, track_addchr, track_free, track_hit, waitfor
Other Functions
Telix v3.00 - SALT Programming Built-in Functions 22
alarm, chatmode, delay, dial, dos, dosfunction, exittelix, help-
screen, loadfon, newdir, redial, redirect_dos, run, send_brk,
set_defprot, set_terminal, show_directory, terminal, tone
Telix v3.00 - SALT Programming Built-in Functions 23
4.2 Complete Function Reference
_________________________________________________________________
alarm
o Summary
alarm(int <seconds>);
o Description
The alarm functions sounds an alarm for a a duration in seconds
given by <seconds>.
o Return Value
The <seconds> argument is returned.
o See Also
tone
o Example
while (!inkey())
alarm(1);
Telix v3.00 - SALT Programming Built-in Functions 24
_________________________________________________________________
box
o Summary
box(int <x>, int <y>, int <x2>, int <y2>, int <style>, int <hollow>,
int <color>);
o Description
The box function is used to create a box on the screen. The box will
have an upper left hand corner of <x>,<y> and a lower right hand
corner of <x2>,<y2>. The box must fit within the confines of the
screen. <color> is the color to use in drawing the box. If <hollow>
is a non-zero (TRUE) value, the inside of the box is not cleared.
<style> selects what kind of box to draw, as follows:
0 Spaces
1 Single lines
2 Double lines
3 Single vertical lines, double horizontal lines
4 Double vertical lines, single horizontal lines
If <style> is any other value, that character is used to construct
the sides of the box.
o Return Value
None.
o See Also
scroll
o Example
box(10, 10, 70, 20, 1, 0, 112); // draw box in inverse color
Telix v3.00 - SALT Programming Built-in Functions 25
_________________________________________________________________
call, calld
o Summary
call(str <scriptname>, <arg1>, <arg2>, <arg3>, ...);
calld(str <scriptname>, <arg1>, <arg2>, <arg3>, ...);
o Description
The call function is used when one script file must call (jump into
and then return from) another. <scriptname> is the name of the
script file to call. If no extension is given, .SLC is assumed.
<arg1> through <argn> are the arguments or parameters to be passed
to the 'main' function of the called script. The value returned is
the value returned by the 'main' function of the called script, and
can be an integer or a string value, although the called script can
not return string variables local to itself. If the script file to
be called is already in memory because it was previously loaded and
made resident, or it is still executing from a previous call, it is
not released but instead the memory image is used. This means that
global variables will have whatever values a previous run through
left in them.
The calld function is exactly the same as the call function, except
that even if an image of the indicated script file is already in
memory, a new copy is still loaded from disk. This ensures that
global variables within the script will be set as defined in the
source file, and that there will be enough stack space, but requires
more memory and is slower.
o Return Value
An integer or string value representing the value returned by the
main function of the called script file. This value must not be a
string variable defined within the called script, for memory rea-
sons. if the indicated script can not be found or loaded, a value of
-1 is returned. If the called script is aborted by the user, a value
of -1 is returned.
o See Also
load_scr, unload_scr, is_loaded
o Example
stat = call("TEST");
if (stat == -1)
prints("Called script could not be loaded or was aborted!");
Telix v3.00 - SALT Programming Built-in Functions 26
_________________________________________________________________
capture
o Summary
capture(str <filename>);
o Description
The capture function is used to open, close, pause, and unpause the
Telix capture file. Depending on what the string variable <filename>
contains, different actions will take place.
If <filename> contains a valid filename (which can include a path),
Telix opens and starts capturing data to that file.
If <filename> is "*CLOSE*", and the capture file is currently open,
it is closed.
If <filename> is "*PAUSE*", and the capture file is currently open,
it is paused.
if <filename> is "*UNPAUSE*", and the capture file is currently open
and paused, it is unpaused.
If <filename> is an empty string (""), Telix takes the same action
as if the user had pressed Alt-L while in terminal mode (which will
depend on whether the capture file is currently open or closed).
o Return Value
A value of -1 is returned if there is a problem performing the indi-
cated function, otherwise a non-zero (TRUE) value is returned.
o See Also
image, printer
o Example
if (capture("TELIX.CAP") == -1)
prints("Error opening capture file!");
Telix v3.00 - SALT Programming Built-in Functions 27
_________________________________________________________________
capture_stat
o Summary
capture_stat();
o Description
The capture_stat function returns an integer value representing the
current status of the capture file, as follows:
0 Capture File is closed
1 Capture File is open
2 Capture File is open and paused
o Return Value
An integer values as described above.
o See Also
usage_stat
_________________________________________________________________
carrier
o Summary
carrier();
o Description
The carrier functions returns a non-zero (TRUE) value if the Carrier
Detect signal coming from the modem is on (high), otherwise it re-
turns a zero (FALSE) value. Note that some modems by default over-
ride the real state of the signal and always send a high. For this
function to work, the modem must be told to supply the real signal.
This function may be used to check if Telix is connected to a remote
service over the modem, as the Carrier Detect signal should be on if
there is a connection. Note that if you are connecting two computers
via a null-modem cable, the value returned will depend on the wiring
of the cable being used.
o Return Value
non-zero (TRUE) or zero (FALSE) based on the state of the Carrier
Detect signal.
o Example
if (carrier())
prints("We are online.");
Telix v3.00 - SALT Programming Built-in Functions 28
_________________________________________________________________
chatmode
o Summary
chatmode(int <echo_remote>);
o Description
The chatmode function enters the chat mode as if the user had
pressed Alt-Y while in terminal mode, If <echo_remote> is non-zero
(TRUE), characters typed by the remote user are echoed back to
him/her, otherwise they are not. The echo feature is for use in Host
Mode implementations.
o Return Value
None.
_________________________________________________________________
cinp_cnt
o Summary
cinp_cnt();
o Description
The cinp_cnt function returns the number of characters waiting in
the received data communications buffer.
o Return Value
An integer value as described above.
o See Also
cgetc
o Examples
if (cinp_cnt() > 10) // if more than 10 chars waiting
handle_stuff(); // do action
while (!cinp_cnt()) // loop until no chars available
;
if (cinp_cnt()) // if something available, get it
c = cgetc();
Telix v3.00 - SALT Programming Built-in Functions 29
_________________________________________________________________
cgetc, cgetct
o Summary
cgetc();
cgetct(int <timeout>);
o Description
The cgetc function returns the first character waiting in the re-
ceived data communications buffer. If there are no characters in the
buffer, a value of -1 is returned. The cinp_cnt function may be used
to see if there are any chars waiting in the buffer.
The cgetct functions returns a character from the communications
port, waiting up to <timeout> tenths of a second for it to arrive.
If a character is already waiting in the communications buffer, it
is immediately returned. If no character is received within the
timeout period, a value of -1 is returned.
o Return Value
An integer value as described above.
o See Also
cinp_cnt
o Example
if (cinp_cnt())
chr = cgetc();
if ((chr = cgetct(100)) == -1)
prints("Timeout!");
Telix v3.00 - SALT Programming Built-in Functions 30
_________________________________________________________________
clear_scr
o Summary
clear_scr();
o Description
The clear_scr function clears the screen and places the cursor in
the upper left corner at position 0,0.
o Return Value
None.
o See Also
scroll
_________________________________________________________________
copychrs
o Summary
copychrs(str <source>, int <target>, int <pos>, int <count>);
o Description
The copychrs function copies a number of characters from one string
into another, Characters from the string <source> are copied into
the string <target> at the position <pos> (note that SALT string
offsets start at 0, not 1 as in some languages). until <count> char-
acters are copied. Only as many characters as will fit in <target>
are copied.
This function is very similar to substr, except that it is not
string oriented, and does not stop copying characters when a 0 value
is encountered.
The substr function copies a portion of one string to another. Char-
acters from position <pos> in string <source> are copied until into
string <target> (note that SALT string offsets start at 0, not 1 as
in some languages). Characters are copied until a 0 (NULL) value is
encountered (normally at the end of every string), or <max> char-
acters are copied. A 0 (NULL) is always copied at the end of the
target string. The 0 does not count as part of the <max>. Only as
many characters as will fit in <target> are copied.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 31
None.
o See Also
copystr, subchrs, substr
o Example
_________________________________________________________________
copystr
o Summary
copystr(str <source>, int <target>, int <pos>, int <count>);
o Description
The copystr function copies one string into another at a certain po-
sition. Characters in string <source> are copied into string
<target> at position <pos> (note that SALT string offsets start at
0, not 1 as in some languages). Characters are copied until a 0
(NULL) value is encountered (normally at the end of every string),
or <max> characters are copied. A 0 (NULL) is always copied at the
end of the target string. The 0 does not count as part of the <max>.
Only as many characters as will fit in <target> are copied.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 32
None.
o See Also
copychrs, substr, subchrs
o Example
_________________________________________________________________
cputc
o Summary
cputc(int <character>);
o Description
The cputc function sends <character> to the communications port.
This is the ASCII value of the character to be sent.
o Return Value
A non-zero (TRUE) value is returned unless the character can not be
sent for some reason, in which case a value of -1 is returned.
o See Also
cputs
o Example
cputc('A');
cputc(27); // send Escape to the comm port
cputc('^M'); // send Ctrl-M (Carriage Return)
cputc(inkeyw());
Telix v3.00 - SALT Programming Built-in Functions 33
_________________________________________________________________
cputs
o Summary
cputs(str <outstr>);
o Description
The cputs function sends the passed string out over the modem port.
A Carriage Return and Line Feed are NOT added after the string.
o Return Value
None.
o See Also
cputs_tr
o Example
cputs("Good-bye");
str password[] = "mypass";
cputs(password);
_________________________________________________________________
cputs_tr
o Summary
cputs_tr(str <outstr>);
o Description
The cputs_tr function sends the passed string out over the modem
port, but pays attention to two output string translation charac-
ters, ^ and ~, described in the Telix manual. This function is re-
ally only useful for sending the modem control strings that the user
has defined in the Configuration Menu.
o Return Value
None.
o See Also
cputs
Telix v3.00 - SALT Programming Built-in Functions 34
o Example
cputs_tr(_modem_init);
cputs_tr("good-bye~yes^M");
_________________________________________________________________
cursor_onoff
o Summary
cursor_onoff(int <state>);
o Description
The cursor_onoff functions turn the blinking cursor on or off (makes
it disappear or reappear), depending on whether state is non-zero
(TRUE) or zero (FALSE).
o Return Value
None.
_________________________________________________________________
curtime
o Summary
curtime();
o Description
The curtime function returns the current date/time as the number of
seconds since Jan 1, 1970. A date/time value in this format is used
by many SALT functions.
o Return Value
An integer value as described above.
o See Also
date, time, tyear, tmonth, tday, thour, tmin, tsec
o Example
// Print the current date
int t;
str s[64];
t = curtime();
date(t, s);
prints(s);
Telix v3.00 - SALT Programming Built-in Functions 35
_________________________________________________________________
date
o Summary
date(int <timeval>, str <buffer>);
o Description
The date function writes out a date in <buffer> in the form
mm/dd/yy, dd/mm/yy, or yy/mm/dd (which is based on the system vari-
able date_format). <timeval> is the date, represented as the number
of seconds since Jan 1, 1970. Time values in this form are returned
by the curtime and filetime functions, among others.
o Return Value
None.
o See Also
time, curtime, filetime
o Example
str s[16];
printsc("The current date is ");
date(curtime(), s);
prints(s);
Telix v3.00 - SALT Programming Built-in Functions 36
_________________________________________________________________
delay, delay_scr
o Summary
delay(int <duration>);
delay_scr(int <duration>);
o Description
The delay function pauses Telix for a length of time specified in
tenths of a second by <duration>. During this pause, everything is
shut off except the asynchronous reception of characters from the
comm port.
The delay_scr function pauses only the execution of the current
script file for the indicated duration. During that time, characters
coming in from the serial port are printed on the terminal screen,
while user keystrokes are also processed.
o Return Value
The <duration> argument is returned.
_________________________________________________________________
delchrs
o Summary
delchrs(str <s>, int <pos>, int <num>);
o Description
The delchrs function is used to remove or delete a number of charac-
ters in a string at a certain position. <s> is the string to handle.
<pos> is the position at which <num> characters will be deleted
(note that the first characters in a SALT string has the position
0). Remaining characters in the string are be shifted left.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 37
None.
o See Also
inschrs
o Example
// remove all but the first and last characters in a string
str s[] = "0123456789";
delchrs(s, 1, strlen(s) - 2);
_________________________________________________________________
dial
o Summary
dial(str <dialstr>, int <maxtries>, int <no_link>);
o Description
The dial function dials the entries specified in <dialstr>. The en-
tries should be entered in the same format as used when typing en-
tries in the dialing directory. If <dialstr> is empty (""), the di-
aling directory is displayed. <maxtries> is the maximum number of
dialing attempts. For example, if the string contains one entry, and
<maxtries> is equal to 5, Telix will attempt to dial the number 5
times. If five entries are indicated, and <maxtries> is equal to 5,
each number will only be attempted once. If <maxtries> is 0, dial-
ing will continue until a connection is established. If an entry is
connected to, and has a linked script file attached, that script
will be run, unless <no_link> is non-zero (TRUE).
o Return Value
If there was a connection, the dial function returns the entry num-
ber of the entry which was connected to (or 1 if a manual number was
dialed). If there was no connection established, 0 is returned. If
the <dialstr> has a bad format, -1 is returned.
Also, when a connection is successfully established, the entry num-
ber of the entry connected to is placed in the system variable
_entry_enum, while the name of the entry connected to is placed in
the system variable _entry_name.
o See Also
redial
_entry_enum, _entry_name
Telix v3.00 - SALT Programming Built-in Functions 38
o Example
int stat;
dial("10 15", 0);
dial("m967-1111", 5);
stat = dial(number_list, 0);
_________________________________________________________________
dos
o Summary
dos(str <command>, int <mode>);
o Description
The dos function calls the DOS command interpreter (usually COM-
MAND.COM, and gives it the passed command string. If the <command>
string is empty (""), Telix will drop into a DOS shell, as if the
Alt-J command had been executed. Make sure that if you specify a
command or program that expects user input you are on hand to give
it. The <mode> argument specifies several options, as follows:
0 Original screen is restored when command is completed.
1 When command is completed, the user is prompted to press a
key and screen is restored as soon as it is pressed.
2 Original screen is not restored when command is completed
This function is very similar to the run function. It should be used
when an internal DOS command is needed or a DOS shell is needed,
otherwise run is preferable as it uses less memory and executes
faster.
o Return Value
The dos function returns a -1 if the command processor can not be
found or there is not enough memory to load it, otherwise a 0 is re-
turned.
o See Also
run, dosfunction
o Example
dos("copy a:*.* c:", 1);
Telix v3.00 - SALT Programming Built-in Functions 39
_________________________________________________________________
dosfunction
o Summary
dosfunction();
o Description
The dosfunction function calls up the 'DOS Functions' menu, as if
the user had pressed Alt-F while in terminal mode.
o Return Value
None.
o See Also
dos, run
_________________________________________________________________
exittelix
o Summary
exittelix(int <returncode>, int <hangup>);
o Description
The exittelix function closes any currently open log file, and exits
Telix to DOS, as if the user had pressed Alt-X while in terminal
mode. The <returncode> argument is the value that should be returned
to DOS. This value can be read by whatever called Telix (e.g., a
batch file using the errorlevel command). The <hangup> option af-
fects what happens if Telix is online. If it is set to non-zero
(TRUE), Telix will hang-up before returning to DOS, otherwise the
connection will not be disturbed.
o Return Value
Since this functions causes Telix to terminate, there is never any
return from it.
o Example
exittelix(0, 1);
exittelix(100, 0);
Telix v3.00 - SALT Programming Built-in Functions 40
_________________________________________________________________
fclearerr
o Summary
fclearerr(int <fh>);
o Description
The fclearerr function clears the error flag assigned to the open
file represented by file handle <fh>. It also clears the End Of File
flag for that file as well.
o Return Value
None.
o See Also
ferror, feof
o Example
int f;
f = fopen("test.dat", "r");
...
if (ferror(f))
fclearerr(f);
_________________________________________________________________
fclose
o Summary
fclose(int <fh>);
o Description
The fclose functions closes the file represented by the file handle
<fh>, which must previously been opened for reading or writing with
the fopen function. If the file was opened for writing, any data
which is still buffered and waiting to be written out to disk is
written before the file is closed.
o Return Value
A return value of -1 indicates a problem closing the file.
o See Also
fopen
Telix v3.00 - SALT Programming Built-in Functions 41
o Example
int f;
f = fopen("test.dat", "w");
...
fclose(f);
_________________________________________________________________
feof
o Summary
feof(int <fh>);
o Description
The feof function determines if the file position for the open file
represented by the file handle <fh> is at the end-of-file position.
o Return Value
A non-zero (TRUE) value is returned if the file position is at the
end of the file.
o See Also
ferror
o Example
int f, chr;
f = fopen("test.dat", "r");
while ((chr = fgetc(f)) != -1) // print contents of file
printc(chr);
if (feof(f))
prints("Reached end of file.");
else
prints("Error reading file");
Telix v3.00 - SALT Programming Built-in Functions 42
_________________________________________________________________
ferror
o Summary
ferror(int <fh>);
o Description
The ferror function checks the error flag for a file represented by
the file handle <fh>. The error flag stays set until it is cleared
with fclearerr or the file is closed.
o Return Value
A non-zero (TRUE) value is returned if the file's error flag is set.
o See Also
fclearerr, feof
o Example
int f;
f = fopen("test.dat", "r"); // open file only for reading
fputs("This should set the error flag!", f);
if (ferror(f))
prints("Error writing to file!");
_________________________________________________________________
fflush
o Summary
fflush(int <fh>);
o Description
The fflush function flushes the buffer associated with the file rep-
resented by file handle <fh>. If the file is opened for writing, any
characters in the buffer are written. If the file is opened for
reading, the buffer is cleared.
o Return Value
A value of -1 is returned if there is a problem flushing the buffer.
o See Also
fopen, fclose
Telix v3.00 - SALT Programming Built-in Functions 43
_________________________________________________________________
fgetc
o Summary
fgetc(int <fh>);
o Description
The fgetc function returns the next character from the file rep-
resented by the file handle <fh>. The file must have been opened for
reading or from reading and writing, using the fopen function.
o Return Value
Returns the character read if successful, or -1 if the end of the
file has been reached or an error is encountered.
o See Also
fopen, fputc
o Example
int f;
f = fopen("test.dat", "r");
while (!feof(f)) // print all the characters in the file
printc(fgetc(f));
Telix v3.00 - SALT Programming Built-in Functions 44
_________________________________________________________________
fgets
o Summary
fgets(str <buffer>, int <n>, int <fh>);
o Description
The fgets function reads characters from the open file indicated by
the file handle <fh> into the string variable <buffer>. Reading
stops when a newline (Line Feed) character is read, and end-of-file
is encountered, a read error occurs, or <n> characters have been
read. The Line Feed character (and the Carriage Return that usually
precedes it on MS-DOS systems) is not kept as part of the string.
Important: The SALT implementation of the fgets() function differs
from the C language function of the same name. While both implemen-
tations read until the Line Feed character, C keeps that character
as part of the input string, while SALT doesn't. This change was
made because in almost every case, the Line Feed is not needed, and
would otherwise have to be manually stripped by the script after ev-
ery read.
o Return Value
A value of -1 is returned if there is a read error, or if there is
an end-of-file before any characters can be read.
o See Also
fopen, fputs
o Example
int f;
str s[100];
f = fopen("test.dat", "r");
while (!feof(f)) // print out contents of text file
{
fgets(s, 100, f);
printsc(s);
}
Telix v3.00 - SALT Programming Built-in Functions 45
_________________________________________________________________
fileattr
o Summary
fileattr(str <filespec>);
o Description
Under the MS-DOS file system, files have a certain attributes which
can determine their functions or the way certain things behave. For
example if a file has the 'hidden' bit set as part of its attribute
byte, when you do a DOS dir command, the file is not shown. Simi-
larly, if a file has the read only bit set, you may not overwrite
it.
The fileattr function returns an integer value representing the at-
tributes of a specified file. <filespec> is the name of the file and
may include a drive and directory portion, as well as the DOS wild-
card characters * and ?.
The value returned is a total of the following attributes.
1 Read only file.
2 Hidden file. The file is not listed when the DOS dir com-
mand is executed.
4 System file. The file is not listed when the DOS dir com-
mand is executed.
8 Volume label. This is the volume name of the disk.
16 Subdirectory. This is a subdirectory name.
32 Archive bit. This is set by DOS whenever a file has been
written to and is then used by some backup software to
check if a file has been modified since last backed-up.
Each of these values is a certain bit in a byte. To test for the ex-
istence of an attribute, the bitwise AND operator should be used.
For example, the following fragment would check if the read only bit
in an attribute is set:
if (attrib & 1)
...
If <filespec> is blank (""), then the attributes of the last file
found with the filefind function is returned. Note that calling
filesize or filetime in the meantime with a non-blank filename would
instead make this call return the attributes of files found with
those functions, as they use the same buffer.
o Return Value
An integer value representing the combined attributes of the in-
Telix v3.00 - SALT Programming Built-in Functions 46
dicated file is returned, or a value of -1 is returned if the in-
dicated file could not be found.
o See Also
filefind, filesize, filetime
o Example
int attr;
str filename[64];
gets(filename, 64);
attr = fileattr(filename);
if (attr & 6) // system _and_ hidden added together
prints("This file is marked as hidden and system");
Telix v3.00 - SALT Programming Built-in Functions 47
_________________________________________________________________
filefind
o Summary
filefind(str <filespec>, int <attrib>, str <buffer>);
o Description
The filefind function is used to search for the existence of one or
more files or disk directories. Filefind puts in <buffer> the name
of the first file matching <filespec>, which may include a drive and
path as well as a filename, and may use the DOS wildcard characters
* and ? (e.g., "*.*", "C:\TELIX\TELIX.EXE", "SCRIPTS\TEST??.*").
<attrib> is the attribute (also see fileattr) which files must
match. The attribute is obtained by adding certain values as fol-
lows:
0 Normal files and read only files
2 Hidden files
4 System files
8 Disk volume label
16 Subdirectory
If the attribute is 0, only normal (and read-only) files are found.
If the volume label is selected, only volume labels will be re-
turned. Any other selected attribute or combination (addition) of
attributes results in those files and all normal files being
matched.
When a matching file, directory, or volume name is found, it is put
in <buffer> (note that the drive and path portion of filespec are
not copied), and a non-zero (TRUE) value is returned. The size,
date/time, and attributes of the matched file can be seen with the
filesize, filetime, and fileattr functions, respectively. If no
files matching the file specification are found, a zero (FALSE)
value is returned.
If <filespec> is blank (""), then filefind searches for the next
matching file. Note that this will not work after an intervening
call to filesize, filetime, or fileattr with a non-blank filename,
as the same buffer is used for searches and to keep data.
o Return Value
A non-zero (TRUE) value is returned if a file matching the speci-
fication was found, otherwise a value of zero (FALSE) is returned.
o See Also
filesize, filetime, fileattr
Telix v3.00 - SALT Programming Built-in Functions 48
o Example
// show all normal files in the current directory
str buf[16], fspec[16] = "*.*";
while (filefind(fspec, 0, buf) != 0)
{
prints(buf); // show file found
fspec = ""; // so we can continue searching for files
}
_________________________________________________________________
filesize
o Summary
filesize(str <filespec>);
o Description
The filesize function returns the size in bytes of the specified
file. <filespec> is the name of the file and may include a drive and
directory portion, as well as the DOS wildcard characters * and ?.
If <filespec> is blank (""), then the size of the last file found
with the filefind function is returned. Note that calling filetime
or fileattr in the meantime with a non-blank filename would instead
make this call return the size of files found with those functions,
as they use the same buffer.
o Return Value
An integer value representing the size of the indicated file is re-
turned, or a value of -1 is returned if the indicated file could not
be found.
o See Also
filefind, filetime, fileattr
o Example
str filespec[24] = "*.*", buf[12];
int size;
siz = filesize("TELIX.EXE"); // get size of file TELIX.EXE
// Add up size of all files int he current directory
siz = 0;
while (filefind(filespec, 0, buf) != 0) // until no more files
{
siz = siz + filesize(""); // get size of last filefound file
filespec = ""; // make sure filespec is "" on sub-
// sequent calls to filefind to
// continue searching for files
}
Telix v3.00 - SALT Programming Built-in Functions 49
_________________________________________________________________
filetime
o Summary
filetime(str <filespec>);
o Description
The filetime function returns the date/time of the specified file.
<filespec> is the name of the file and may include a drive and di-
rectory portion, as well as the DOS wildcard characters * and ?.
The values returned represents the file's modification date as the
number of seconds since Jan 1, 1970. A date/time in this form can be
used by the date, time, tyear, tmonth, tday, thour, tmin, tsec, and
other functions.
If <filespec> is blank (""), then the date/time of the last file
found with the filefind function is returned. Note that calling
filesize or fileattr in the meantime with a non-blank filename would
instead make this call return the time/date of files found with
those functions, as they use the same buffer.
o Return Value
An integer value representing the date/time of the indicated file is
returned, or a value of -1 is returned if the indicated file could
not be found.
o See Also
filefind, filesize, fileattr
o Example
int time;
str s[16];
time = filetime("TELIX.EXE");
if (time == -1)
prints("'TELIX.EXE" could not be found!");
else
{
printsc("TELIX.EXE was created at ");
time(time, s);
printsc(s);
printsc(" on ");
date(time, s);
printsc(s);
}
// this example assumes both files exist
if (filetime("FILE1") < filetime("FILE2"))
prints("FILE1 is older than FILE2");
Telix v3.00 - SALT Programming Built-in Functions 50
else
prints("FILE1 is newer than FILE2");
_________________________________________________________________
flushbuf
o Summary
flushbuf();
o Description
The flushbuf function flushes (throws away) any characters that may
be waiting in Telix's remote input buffer. One use for this command
is to get rid of unwanted line noise.
o Return Value
None.
Telix v3.00 - SALT Programming Built-in Functions 51
_________________________________________________________________
fnstrip
o Summary
fnstrip(str <filename>, int <specifier>, str <target>);
o Description
The fnstrip function allows specific parts of a filename to be ex-
tracted. In the MS-DOS operating system, a filename can consist of
up to four parts, the drive, the path, the name, and the extension
(e.g., C:\TELIX\TELIX.FON). fnstrip processes the filename specified
in <filename>, and depending on the value of <specifier>, places any
combination of these four parts in the <target> string. Legal values
for <specifier> and their results are as follows:
<specifier> Filename portion copied
0 Full file name
1 All except the drive
2 Drive, name, and extension
3 Name and extension
4 Drive, path, and name (no extension)
5 Path and name (no extension)
6 Drive and name (no extension)
7 Name only (no extension)
12 Drive and path only
13 Path only
14 Drive only
o Return Value
None.
o See Also
filefind
o Example
str filename[64], shortname[16];
gets(filename, 64); // ask for a filename
fnstrip(filename, 3, shortname); // keep only name & extension
Telix v3.00 - SALT Programming Built-in Functions 52
_________________________________________________________________
fopen
o Summary
fopen(str <name>, str <mode>);
o Description
The fopen function is used to open a disk file for reading and/or
writing. The file to be opened is given by <name>. <mode> is a
string indicating for what use the file should be opened. Legal val-
ues for mode are:
"r" Opens for reading
"w" Opens for writing (truncates any existing file with
the same name)
"a" Opens for appending (writing at the end of the file).
Creates the file if it doesn't exist.
"r+" Opens for reading and writing. Initial position at
the beginning of the file (the file must already ex-
ist).
"w+" Opens for reading and writing. If the file exists its
contents are destroyed.
"a+" Opens for reading and appending. Creates the file if
it doesn't exist.
If a file is opened for both reading and writing (when "r+", "w+",
or "a+" are used as the mode), an fseek operation is necessary be-
fore switching from one to the other.
o Return Value
The fopen function returns a 'handle' which is an integer number by
which this file is to be referred to until it is finally closed. A
value of 0 is returned if the file can not be opened (because it
doesn't exist, because a disk error occurred, or because there are
no more file handles available). Only up to 8 files may be opened at
a time. It is therefore very important to close open files if they
are no longer needed and when a script is done, or else all avail-
able file handles will become used up.
o See Also
fclose
o Example
int f;
f = fopen("data.txt", "r"); // open the file for reading
if (f == 0)
prints("Error opening file!");
Telix v3.00 - SALT Programming Built-in Functions 53
_________________________________________________________________
fputc
o Summary
fputc(int <c>, int <fh>);
o Description
The fputc function writes a character to the file indicated by the
file handle <fh>. <c> is the character to write.
o Return Value
The character written is returned, unless there is an error, in
which case a value of -1 is returned.
o See Also
fputs, fgetc
o Example
int f, i;
str teststr[] = "This is a test string";
f = fopen("test.dat", "w");
for (i = 0; i < 21; ++i) // write out string to file
fputc(subchr(teststr, i), f); // character by character
_________________________________________________________________
fputs
o Summary
fputs(str <s>, int <fh>);
o Description
The fputs function writes a string to the file represented by file
handle <fh>. The string must be 512 bytes in length or less (all
strings end in a zero (0) value, the use of which is usually trans-
parent; characters are written until this 0 is encountered. The 0 is
not written).
o Return Value
A 0 value is returned if the write is successful, a non-zero value
if it is not.
o See Also
fputc, fgets
Telix v3.00 - SALT Programming Built-in Functions 54
o Example
int f, i;
f = fopen("test.dat", "w");
for (i = 0; i < 100; ++i) // write out "Hello" and a new-
fputs("Hello^M^J", f); // line one hundred times
_________________________________________________________________
fread
o Summary
fread(str <buf>, int <count>, int <fh>);
o Description
The fread function reads up to <count> bytes from the file repre-
sented by file handle <fh>. Characters are written to the <buf>
variable, which must be large enough.
o Return Value
The number of bytes actually read is returned, which may be less
than <count> if an error occurs or and end-of-file is encountered.
The ferror and feof functions should be used to distinguish an error
from an end-of-file condition.
o See Also
fwrite
o Example
int f;
str buffer[40];
f = fopen("test.dat", "r");
fseek(f, 1000, 0); // goto offset 1000 in file
fread(buffer, 40, f); // and read 40 bytes of data
Telix v3.00 - SALT Programming Built-in Functions 55
_________________________________________________________________
fseek
o Summary
fseek(int <fh>, int <offset>, int <origin>);
o Description
The fseek function sets the position of the file pointer in the file
represented by the file handle <fh>. The file position is where the
next read or write will take place. <offset> is the signed offset
from the location specified by <origin>. Legal values for <origin>
are:
0: Beginning of file.
1: Current position.
2: End of file.
The pointer can be positioned anywhere in the file, and even past
the end of the file (which will extend it). It is illegal to try to
position the pointer before the beginning of the file however.
o Return Value
If successful, fseek returns a 0 value, otherwise a non-zero value
is returned.
o See Also
ftell
o Example
int f;
f = fopen("test.dat", "r");
fseek(f, 0, 0); // go to offset 0 in file
fseek(f, 1000, 0); // go to offset 1000 in file
fseek(f, -5, 1); // go back 5 places in file
fseek(f, 0, 2); // go to the end of the file
Telix v3.00 - SALT Programming Built-in Functions 56
_________________________________________________________________
ftell
o Summary
ftell(int <fh>);
o Description
The ftell function returns the current file position in the file
represented by file handle <fh>.
o Return Value
An integer value as described above. A -1 value is returned if an
error occurs.
o See Also
fseek
_________________________________________________________________
fwrite
o Summary
fwrite(str <buf>, int <count>, int <fh>);
o Description
The fwrite function writes bytes to the file represented by the file
handle <fh>. <count> number of bytes are written from <buf>.
o Return Value
The number of bytes actually written are returned, which may be less
than <count> if an error occurred.
o See Also
fread
o Example
int f;
str buffer[] = "1234567890123456789012345";
f = fopen("test.dat", "w");
fwrite(buffer, 25, f); // write test pattern to file
Telix v3.00 - SALT Programming Built-in Functions 57
_________________________________________________________________
get_baud
o Summary
get_baud();
o Description
The get_baud function returns an integer value which is the current
baud rate in use on the current communications port (300 through
115200).
o Return Value
As described above.
o See Also
get_parity, get_datab, get_stopb, get_port
o Example
prints("The current baud rate is ");
printn(get_baud());
prints("");
_________________________________________________________________
get_datab
o Summary
get_datab();
o Description
The get_datab function returns the data bits setting in use on the
current communications port (7 or 8).
o Return Value
As described above.
o See Also
get_baud, get_parity, get_stopb, get_port
Telix v3.00 - SALT Programming Built-in Functions 58
_________________________________________________________________
get_parity
o Summary
get_parity();
o Description
The get_parity function returns an integer value which represents
the current parity setting in use on the current comm port.
o Return Value
Returned values are as follows:
0 No parity
1 Even parity
2 Odd parity
o See Also
get_baud, get_datab, get_stopb, get_port
_________________________________________________________________
get_port
o Summary
get_port();
o Description
The get_port function returns the number (1 through 8) of the cur-
rent communications port being used.
o Return Value
As described above.
o See Also
get_baud, get_datab, get_parity, get_stopb
o Example
prints("Currently using COM");
printn(get_port());
prints("");
Telix v3.00 - SALT Programming Built-in Functions 59
_________________________________________________________________
get_stopb
o Summary
get_stopb();
o Description
The get_stopb function returns the stop bits setting in use on the
current com port (1 or 2).
o Return Value
As described above.
o See Also
get_baud, get_datab, get_parity, get_port
_________________________________________________________________
gets
o Summary
gets(str <buffer>, int <max>);
o Description
The gets function allows the user to enter a complete string, and
use the arrow keys to edit it while it is being entered. <buffer> is
the string variable where the string should be put, while <max> is
the maximum number of characters the user may enter (from 0 to 80).
The user may edit the string as it is being entered, with the Left-
Arrow, Right-Arrow, Ctrl-Left-Arrow, and Ctrl-Right-Arrow keys as it
is being entered, and insert mode may be toggled on/off with the INS
key. String entry is over when the user presses Enter (Carriage Re-
turn on some computers). The user may press Esc to abort string en-
try, in which case the resulting string will have a length of 0.
o Return Value
The number of characters entered by the user are returned. If the
user pressed Esc to abort string entry, a value of -1 is returned.
o See Also
getsxy
Telix v3.00 - SALT Programming Built-in Functions 60
o Example
int n;
str password[8];
printsc("Enter a password? ");
n = gets(password, 8);
_________________________________________________________________
getsxy
o Summary
getsxy(str <targets>, int <max>, int <x>, int <y>, int <color>);
o Description
The getsxy function is similar to the gets function, but the x,y lo-
cation of string entry may be specified, as well as a color at-
tribute. <buffer> is the string variable where the string should be
put, while <max> is the maximum number of characters the user may
enter (from 0 to 80). The cursor will be moved to <x>,<y>, and text
entered will use a color as described by <color>.
The user may edit the string as it is being entered, with the Left-
Arrow, Right-Arrow, Ctrl-Left-Arrow, and Ctrl-Right-Arrow keys as it
is being entered, and insert mode may be toggled on/off with the INS
key. String entry is over when the user presses Enter (Carriage Re-
turn on some computers). The user may press Esc to abort string en-
try, in which case the resulting string will have a length of 0.
o Return Value
The number of characters entered by the user are returned. If the
user pressed Esc to abort string entry, a value of -1 is returned.
o See Also
gets
o Example
int n;
str filename[64] = "C:\TELIX\TELIX.EXE";
// allow use to enter filename in black on white
// at current cursor position
n = getsxy(filename, 64, getx(), gety(), 112);
Telix v3.00 - SALT Programming Built-in Functions 61
_________________________________________________________________
getx, gety
o Summary
getx();
gety();
o Description
The getx function returns the current column (horizontal x axis) po-
sition of the cursor on the screen.
The gety function returns the current row (vertical y axis) position
of the cursor on the screen.
o Return Value
Returned values will range from 0 for the leftmost column to 79 for
the rightmost column, for the getx function.
Returned values range from 0 for the upper edge of the screen to 24
for the lower edge, for the gety functions..
o See Also
gotoxy
_________________________________________________________________
gotoxy
o Summary
gotoxy(int <xpos>, int <ypos>);
o Description
The gotoxy function positions the cursor at the screen coordinates
given by <xpos> and <ypos>. Note that 0,0 is the upper left corner.
On a 80x25 text screen, the lower right corner would be 79,24.
o Return Value
None.
o See Also
getx, gety
Telix v3.00 - SALT Programming Built-in Functions 62
o Example
gotoxy(0, 0); // go to the top left corner
gotoxy(79, 24); // go to the bottom right corner
_________________________________________________________________
hangup
o Summary
hangup();
o Description
The hangup function tries to hang-up the modem, exactly as if the
user had pressed Alt-H while in terminal mode. This is accomplished
by first dropping (turning off) a signal called the DTR line, and if
that is unsuccessful, sending the hang-up string defined in the
configuration menu.
o Return Value
A non-zero (TRUE) value is returned if the hang-up is successful,
otherwise a zero (FALSE) value is returned.
_________________________________________________________________
helpscreen
o Summary
helpscreen();
o Description
The helpscreen function displays the help/status screen, as if the
user had pressed the appropriate key while in terminal mode.
o Return Value
None.
Telix v3.00 - SALT Programming Built-in Functions 63
_________________________________________________________________
inkey, inkeyw
o Summary
inkey();
inkeyw();
o Description
The inkey function returns a character from the keyboard, but does
not wait for a key to be pressed.
The inkeyw function returns a character from the keyboard, and waits
for a key to be pressed if the keyboard buffer is empty.
Note that Telix while executing a script file checks the keyboard
between every command to see if the user wants to abort the script.
For these commands to work, this keyboard checking must be disabled.
This is done by setting the _scr_chk_key system variable to a non-
zero (FALSE) value (that variable is further described in the sec-
tion on system variables).
o Return Value
inkey returns the first character in the keyboard buffer, or a value
of 0 if the keyboard buffer is empty.
inkeyw waits until a key has been pressed if none is available in
the keyboard buffer, and returns that value.
Both of these functions also return extended key code values which
are not part of the ASCII character set (for example, the code for
Alt-D). These values are described in the Appendix.
o Example
chr = inkey();
Telix v3.00 - SALT Programming Built-in Functions 64
_________________________________________________________________
inschrs
o Summary
inschrs(str <source>, str <target>, int <pos>, int <num>);
o Description
The inschrs function is used to insert characters from one string
into another at a specific position, shifting existing characters to
the right. Characters are taken from <source> and placed in
<target>, at an offset indicated by <pos>. Note that string offsets
are numbered starting at 0, so the first character would have an
offset of 0, the second 1, etc. Only <num> characters are inserted,
and existing characters are shifted to the right (and are lost if
they shift past the space allocated for the string).
o Return Value
None.
o See Also
copystr, copychrs
o Example
str test[24] = "Good-bye";
// add "Hello" to the front of the existing string
inschrs("Hello ", test, 0, 6);
Telix v3.00 - SALT Programming Built-in Functions 65
_________________________________________________________________
isalnum - isupper
o Summary
isalnum(int <c>); Test for alphanumeric ('A'-'Z', 'a'-'z', or '0'-
'9'
isalpha(int <c>); Test for letter ('A'-'Z' or 'a'-'z')
isascii(int <c>); Test for ASCII value (0-255)
iscntrl(int <c>); Test for Control character (0-31 or 127)
isdigit(int <c>); Test for digit ('0'-'9')
islower(int <c>); Test for lower case ('a'-'z')
isupperint <c>); Test for upper case ('A'-'Z')
o Description
The functions listed above test an integer value and return a non-
zero (TRUE) value if the test condition is satisfied, or a zero
(FALSE) if it is not.
Except for isascii, these functions give valid results only for in-
teger values in the ASCII character set, that is, values for which
isascii is true.
o Return Value
A non-zero (TRUE) value is returned if the test condition is sat-
isfied, a 0 (FALSE) value otherwise.
Telix v3.00 - SALT Programming Built-in Functions 66
_________________________________________________________________
is_loaded
o Summary
is_loaded(str <filename>);
o Description
The is_loaded function is used to determine if a SALT script, in-
dicated by <filename> is currently loaded into memory. The script
can be in memory if it was explicitly loaded with the load_script
function, or is still in memory because it previously was run and
did not finish executing. If filename does not include an extension,
".SLC" is automatically added.
o Return Value
A non-zero (TRUE) values is returned if the indicated script file is
in memory, otherwise a zero (FALSE) value is returned.
o See Also
load_scr, unload_scr
o Example
if (!is_loaded("TESTSCR")) // make sure script is in memory
load_scr("TESTSCR");
_________________________________________________________________
itos
o Summary
itos(int <value>, str <s>);
o Description
The itos function writes out the digits of the supplied integer
value to <s>.
o Return Value
None.
o See Also
stoi
Telix v3.00 - SALT Programming Built-in Functions 67
o Example
int chr;
str s[16];
chr = keyinw(); // get a user keystroke
itos(chr, s); // and print out ASCII value of character
prints(s);
_________________________________________________________________
keyget
o Summary
keyget(int <key>, int <table>, str <buffer>);
o Description
The keyget function is used to look at what text is assigned to a
key. <key> is an integer value representing the key (as described in
the appendix). Any macro text assigned to this key will be placed in
<buffer>. Telix keeps two key macro definition tables in memory at
all times, a user key table, and a terminal key table, loaded in
whenever the current terminal is changed. If <table> is 0, the key
is assumed to be in the user table. If <table> is 1, the key is as-
sumed to be in the terminal table.
o Return Value
None.
o See Also
keyset, keyload, keysave
o Example
str s[100];
prints("Text currently assigned to the F1 key in user table is:)"
keyget(0x3a00, 0, s);
prints(s);
Telix v3.00 - SALT Programming Built-in Functions 68
_________________________________________________________________
keyload
o Summary
keyload(str <fname>, int <table>);
o Description
The keyload function is used to load a keyboard macro definition
file into Telix. <fname> is the name of the definition file (if no
extension is given, .KEY is assumed). Telix always keeps two defini-
tion tables in memory, a relatively constant user table, and a ter-
minal table which changes with each different terminal and holds the
proper key assignments for that terminal. If <table> is 0, then the
definitions are loaded into the user table. If <table> is 1, the
definitions are loaded into the terminal table.
o Return Value
A value of -1 is returned if there are problems loading the key
file, otherwise a non-zero (TRUE) value is returned.
o See Also
keysave, keyget, keyset
o Example
keyload("SPECIAL", 0);
_________________________________________________________________
keysave
o Summary
keysave(str <fname>, int <table>);
o Description
The keysave function is used to save the current macro key text def-
initions to a disk file. <fname> is the file to save the definitions
to, and if no extension is given, ".KEY" is added. Telix always
keeps two key definition tables in memory, a relatively constant
user table, and a terminal table which changes with each different
terminal and holds the proper key assignments for that terminal. If
<table> is 0, then the definitions from the user table are saved. If
<table> is 1, the definitions from the terminal table are saved.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 69
A value of -1 is returned if there is a problem writing to the file,
otherwise a non-zero (TRUE) value is returned.
o See Also
keyload, keyget, keyset
_________________________________________________________________
keyset
o Summary
keyset(int <key>, int <table>, str <text>);
o Description
The keyset function is used to assign text to a key. <key> is an in-
teger value representing the key (as described in the appendix).
<text> is what to assign to this key. Telix always keeps two key
definition tables in memory, a relatively constant user table, and a
terminal table which changes with each different terminal and holds
the proper key assignments for that terminal. If <table> is 0, the
key definition in the user table is affected. If <table> is 1, the
key definition in the terminal table is affected.
o Return Value
None.
o See Also
keyget, keyload, keysave
o Example
// Assign a name to the F1 key in the user table
// Note that if the terminal table also holds a
// definition for that key it will take precedence
keyset((0x3a00, 0, "Joe Smith");
Telix v3.00 - SALT Programming Built-in Functions 70
_________________________________________________________________
loadfon
o Summary
int loadfon(str <filename>);
o Description
The loadfon function loads the given dialing directory file. The
complete name must be given, including any extension (e.g. .FON) or
the disk drive/directory if the file is not in the current di-
rectory.
o Return Value
A non-zero (TRUE) value is returned if the dialing directory file is
successfully loaded. If some sort of error occurs (file does not ex-
ist, file reading error, etc.) a zero (FALSE) value is returned.
_________________________________________________________________
load_scr
o Summary
load_scr(str <filename>);
o Description
When a script is run (either by the user manually running it from
terminal mode, or from within another script), it is usually loaded
from disk. The load_scr function is used to load a script into mem-
ory ahead of time, providing a savings in time when the script must
be run repeatedly. <filename> is the name of the script file to
load, and if no extension is given, ".SLC" is assumed.
o Return Value
If there is a problem loading the script file (it is not there or
there is not enough memory),a value of -1 is returned. Otherwise a
non-zero (TRUE) value is returned.
o See Also
unload_scr, is_loaded
o Example
int stat;
stat = load_scr("TEST"); // load TEST.SLC
Telix v3.00 - SALT Programming Built-in Functions 71
_________________________________________________________________
newdir
o Summary
newdir(<directory>);
o Description
The newdir function is used to changed the current drive and/or di-
rectory. The <directory> argument should be the drive and/or direc-
tory to change to.
o Return Value
A non-zero (TRUE) value is returned if the function is successful,
otherwise a zero (FALSE) values is returned (if the drive or direc-
tory is illegal or doesn't exist).
o See Also
dos, run
o Example
newdir("C:\TELIX");
_________________________________________________________________
printc
o Summary
printc(int <chr>);
o Description
The printc function prints the character represented by the ASCII
value <chr> to the terminal screen.
o Return Value
<chr> is returned.
o See Also
prints, printsc, printn
Telix v3.00 - SALT Programming Built-in Functions 72
o Example
printc('A');
printc(7); // print ASCII value 7 (BELL sound)
printc(keyinw()); // print user keypress
_________________________________________________________________
printer
o Summary
printer(int <state>);
o Description
The printer function is used within a script file to turn the
printer on or off, as if the user had pressed the appropriate key in
terminal mode. If <state> is a non-zero (TRUE) value, echoing to the
printer is turned on, otherwise echoing is turned off
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 73
None.
o See Also
capture
o Example
printer(1); // turn on printer log
_________________________________________________________________
printn
o Summary
printn(int <num>);
o Description
The printn function prints the passed integer number to the terminal
screen. The cursor is NOT advanced to the beginning of the next
line.
o Return Value
The value of the passed integer is returned.
o See Also
prints, printsc, printc
o Example
printsc("Current baud rate is ");
printn(get_baud);
Telix v3.00 - SALT Programming Built-in Functions 74
_________________________________________________________________
prints, printsc
o Summary
prints(str <outstr>);
printsc(str <outstr>);
printsc_trm(str <outstr>);
o Description
The prints function prints the passed string at the current cursor
position on the screen, followed by a Carriage Return and Line Feed
(which places the cursor at the beginning of the next line).
The printsc function prints the passed string at the current cursor
position on the screen. The cursor is not advanced to the next line,
hence the 'c', which stands for continuous.
The printsc_trm function is similar to the above, except that out-
putted characters pass through the current terminal emulator, so
terminal escape sequences may be included in output strings.
o Return Value
None.
o See Also
printn, printc
o Example
prints("Hello");
printsc("Hello^M^J"); // same effect as above
printsc_trm("^[[H"); // go to top left corner in VT102 emulation
Telix v3.00 - SALT Programming Built-in Functions 75
_________________________________________________________________
pstra, pstraxy
o Summary
pstra(str <s>, int <color>);
pstraxy(str <s>, int <x>, int <y>, int <color>);
o Description
The pstra (Print STRing with color Attribute) function is used to
print a string to the screen, similar to the prints/printsc func-
tions. This function is much faster however, and should be used when
speed is important. As well, it allows a color to be specified for
the text. <s> will be printed to the screen at the current cursor
position using a color as specified by <color>.
The pstraxy function is similar to the above, but allows you to
specify where to print the string. The string is printed at <x>,<y>,
with 0,0 being the upper left corner of the screen.
Note that prints goes through a basic TTY type terminal emulator, so
strings printed using it may contain the basic cursor control code,
while pstra writes directly to the screen, ignoring these sequences.
o Return Value
None.
o See Also
prints, printsc
o Example
pstraxy("Enter name:", 10, 10, 112); // print in inverse text
Telix v3.00 - SALT Programming Built-in Functions 76
_________________________________________________________________
receive
o Summary
receive(int <protocol>, str <name>);
o Description
The receive function is used to receive (download) one or more files
from another system. <protocol> is the letter used to select the ap-
propriate protocol from the actual download menu in Telix (e.g., 'X'
for Xmodem), as follows:
'A' ASCII
'K' Kermit
'M' Modem7
'S' SEAlink
'T' Telink
'X' Xmodem
'1' Xmodem-1k
'G' Xmodem-1k-g
'Y' Ymodem
'E' YmodEm-g
'Z' Zmodem
If an external protocol is defined, <protocol> may also be the key
used to select it. <name> is the name the file should take. For pro-
tocols which pass the name, such as SEAlink, Zmodem, Ymodem (batch),
and others, the name field should be an empty string, "". If a down-
load directory has been defined in the Configuration Menu, received
files will go there, unless the <name> string explicitly includes a
path to another drive/directory.
o Return Value
A value of -1 is returned if the transfer was aborted, except if the
Carrier (connection) was lost, in which case a value of -2 is re-
turned.
o See Also
send, _down_dir
o Example
int result;
result = receive('X', "TEST.EXE");
if (result < 0)
prints("File transfer failed!");
Telix v3.00 - SALT Programming Built-in Functions 77
_________________________________________________________________
redial
o Summary
redial(str <dialstr>, int <maxtries>, int <no_link>);
o Description
The redial function dials the entries specified in <dialstr>. The
entries should be entered in the same format as used when typing en-
tries in the dialing directory. If <dialstr> is empty (""), the re-
dial queue is presented to the user, as if Alt-Q was pressed while
in terminal mode. <maxtries> is the maximum number of dialing at-
tempts. For example, if the string contains one entry, and
<maxtries> is equal to 5, Telix will attempt to dial the number 5
times. If five entries are indicated, and <maxtries> is equal to 5,
each number will only be attempted once. If <maxtries> is 0, dialing
will continue until a connection is established. If an entry is con-
nected to, and has a linked script file attached, that script will
be run, unless <no_link> is non-zero (TRUE).
o Return Value
If there was a connection, the redial function returns the entry
number of the of the entry which was connected to (or 1 if a manual
number was dialed). If there was no connection established, 0 is re-
turned. If the <dialstr> has a bad format, -1 is returned.
Also, when a connection is successfully established, the entry num-
ber of the entry connected to is placed in the system variable
_entry_enum, while the name of the entry connected to is placed in
the system variable _entry_name.
o See Also
dial
_entry_enum, _entry_name
o Example
int stat;
str number_list[] = "1 4 27";
redial("10 15", 0);
redial("m967-1111", 5);
stat = redial(number_list, 0);
Telix v3.00 - SALT Programming Built-in Functions 78
_________________________________________________________________
run
o Summary
run(str <filename>, str <comline>, int <mode>);
o Description
The run function executes the indicated file. The indicated file
must either be in the current directory, be on the DOS PATH, or must
include the full path to the file (i.e., specify the drive and/or
directory). Make sure that if you run a program that expects user
input you are on hand to give it. The <comline> parameter is the
command line which should be passed to the called program. The
<mode> argument specifies several options, as follows:
0 Original screen is restored when program is completed.
1 When program is completed, the user is prompted to press a
key and screen is restored as soon as it is pressed.
2 Original screen is not restored when program is completed
This function is similar to the dos function. Because it uses less
memory and loads faster, it is preferable to that function unless a
DOS Batch file has to be run, or an internal DOS command must be
specified, in which case the dos function has to be used.
o Return Value
The run function returns a -1 if the file can not be run (because it
can not be found or there is not enough memory). Any other value is
the value returned by the called program (usually 0), but a positive
value may also result when the called program is aborted.
o See Also
dos, dosfunction
o Example
run("CS test", 1);
Telix v3.00 - SALT Programming Built-in Functions 79
_________________________________________________________________
scroll
o Summary
scroll(int <x>, int <y>, int <x2>, int <y2>, int <lines>, int
<color>);
o Description
The scroll function is used to scroll or clear a region of the
screen. The area to handle is defined by <x>,<y> as the upper left
corner, and <x2>,<y2> as the lower right corner (the upper left cor-
ner of the screen is 0,0). If the <lines> parameter is a positive
value, text within the region is scrolled up that many lines. If
<lines> is a negative value, text within the region is scrolled down
that many lines. If <lines> is equal to 0, the entire region is
cleared. Empty lines scrolled into the region will have a color of
<color>.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 80
None.
o See Also
box
o Example
scroll(0, 0, 79, 24, 10, 7); // scroll screen up 10 lines
_________________________________________________________________
send
o Summary
send(int <protocol>, str <name>);
o Description
The send function is used to send (upload) one or more files to an-
other system over the comm port. <protocol> is the letter used to
select the appropriate protocol from the actual download menu in
Telix (e.g., 'X' for Xmodem) as follows:
'A' ASCII
'K' Kermit
'M' Modem7
'S' SEAlink
'T' Telink
'X' Xmodem
'1' Xmodem-1k
'G' Xmodem-1k-g
'Y' Ymodem
'E' YmodEm-g
'Z' Zmodem
If an external protocol is defined, <protocol> may also be the key
used to select. <name> is the file(s) to send. <name> may include
the DOS wildcard characters * and ?, in which case all matching
files will be sent (however the protocol used must be capable of
sending more than one file at a time, e.g., SEAlink, Zmodem, Ymodem
(batch), etc.). If an upload directory has been defined in the Con-
figuration Menu, Telix will look there for files specified to be
sent, unless the <name> string explicitly includes a path to another
drive/directory.
o Return Value
A value of -1 is returned if the transfer was aborted, except if the
carrier (connection) was lost, in which case a value of -2 is re-
turned.
o See Also
receive, _up_dir
Telix v3.00 - SALT Programming Built-in Functions 81
_________________________________________________________________
send_brk
o Summary
send_brk(<duration>);
o Description
The send_brk function sends a sustained break signal over the modem
port, for a period of time, specified in tenths of a second, by
<duration>.
o Return Value
None.
_________________________________________________________________
set_cparams
o Summary
set_cparams(int <baud>, int <parity>, int <data>, int <stop>);
o Description
The set_cparams function is used to set the communications param-
eters in use on the current communications port. Allowable <baud>
values are 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, and
115200. <parity> is an integer number which stands for the parity to
use. Allowable values are 0, 1, and 2, which stand for None, Even,
and Odd parity, respectively. <data> is the data bits setting to
use; allowable values are 7 or 8. <stop> is the stop bits setting to
use; allowable values are 1 or 2. Note that some combinations of
settings are illegal.
o Return Value
If all the settings are legal values, a non-zero (TRUE) value is re-
turned, otherwise a value of -1 is returned.
o See Also
set_port
o Example
set_cparams(2400, 0, 8, 1);
set_cparams(9600, get_parity(), get_datab(), get_stopb());
Telix v3.00 - SALT Programming Built-in Functions 82
_________________________________________________________________
set_defprot
o Summary
set_defprot(int <protocol>);
o Description
The set_defprot function is used to set the default file transfer
protocol presented to the user when a file transfer is requested.
<protocol> is the letter used to select the appropriate protocol at
the file transfer menu (see the description of the receive function
for possible options).
o Return Value
None.
o See Also
receive, send
o Example
set_defprot('Z'); // Select Zmodem as default protocol
_________________________________________________________________
setchr
o Summary
setchr(str <buf>, int <pos>, int <c>);
o Description
The setchr function puts the character <c> at position <pos> in the
string indicated by <buf>.
o Return Value
The character <c> is returned.
o See Also
setchrs, subchr
o Example
int i;
str s[100];
for (i = 0; i < 10; ++i) // set first 10 characters to 'A'
setchr(s, i, 'A');
Telix v3.00 - SALT Programming Built-in Functions 83
_________________________________________________________________
setchrs
o Summary
setchrs(str <buf>, int <pos>, int <c>, int <count>);
o Description
The setchrs function is used to set a range of characters in a
string to the same value. <buf> is the string in which characters
will be set, starting at an offset indicated by <pos> (note that the
first character in a SALT string has an offset of 0, the second, 1,
and so on). <count> characters will be set to the value of <c>.
o Return Value
None.
o See Also
setchr, subchrs
o Example
str s[100];
// zero out an entire string
setchrs(s, 0, 0, strmaxlen(s));
// set the first ten characters to 'A'
setchrs(s, 0, 'A', 10);
_________________________________________________________________
set_port
o Summary
set_port(int <port>);
o Description
The set_port function is used to select a communications port to
use. Allowable values for <port> are 1 through 8.
o Return Value
If the new port can be successfully initialized, a non-zero (TRUE)
value is returned, otherwise a value of -1 is returned.
o See Also
set_cparams
Telix v3.00 - SALT Programming Built-in Functions 84
_________________________________________________________________
set_terminal
o Summary
set_terminal(str <terminal_name>);
o Description
The set_terminal function is used to switch the current terminal be-
ing emulated. <terminal_name> is the name of the new terminal to
use, as follows:
"TTY"
"ANSI-BBS"
"VT102"
"VT52"
"AVATAR"
o Return Value
A value of -1 is returned if there is a problem switching to the in-
dicated terminal emulator, otherwise a non-zero (TRUE) value is re-
turned.
o Example
set_terminal("VT102");
Telix v3.00 - SALT Programming Built-in Functions 85
_________________________________________________________________
show_directory
o Summary
show_directory(str <filespec>, int <cecho>, int <carrier>);
o Description
The show_directory function displays a files directory listing to
the screen and optionally echoes it to the comm port. The <filespec>
is the file mask to use (e.g., "*.*"), and may also include a drive
and/or directory, just like the DOS 'dir' command. If the <cecho>
argument is non-zero (TRUE), the listing is also be echoed to the
comm port. If the <carrier> argument is non-zero (TRUE) and the
listing is being echoed to the comm port, the carrier signal is mon-
itored in case the connection is lost (which aborts the display).
The user is prompted to press a key after every screen full of data.
o Return Value
None.
o See Also
dos, dosfunction
o Example
show_directory("*.DOC", 0, 0);
_________________________________________________________________
status_wind
o Summary
status_wind(str <message>, int <duration>);
o Description
The status_wind function is used to display a status message,
<message>, in a pop up window. <duration> is the time in tenths of
seconds to display the window, after which it is removed, and the
previous contents of that screen area are restored.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 86
None.
o See Also
box, pstra, pstraxy
o Example
status_wind("File not found!", 10);
_________________________________________________________________
stoi
o Summary
stoi(str <s>);
o Description
The stoi function assumes that <s> is a string which contains an in-
teger number, written out. It processes the string digit by digit
and returns that value. For example, stoi("123") would return the
integer value 123. Processing stops at the first non-digit charac-
ter. If an empty or invalid string is parsed, a value of 0 is re-
turned.
o Return Value
An integer value as described above.
o See Also
itos
o Example
str s[] = "123";
if (stoi(s) == 123)
prints("This will always be printed!");
Telix v3.00 - SALT Programming Built-in Functions 87
_________________________________________________________________
strcat
o Summary
strcat(str <string1>, str <string2>);
o Description
The strcat function concatenates (adds or appends) one string to the
other. <string2> is added to the end of <string1>. If <string1> is
not large enough only as many characters as will fit are added.
o Return Value
None.
o Example
str s[80] = "hello";
strcat(s, "good-bye");
if (s == "hellogoodbye")
prints("This will always be printed");
Telix v3.00 - SALT Programming Built-in Functions 88
_________________________________________________________________
strchr
o Summary
strchr(str <s>, int <pos>, int <c);
o Description
The strchr function is used to search for a character within a
string. <s> is the string to search, and <pos> is the starting posi-
tion of the search, and <c> is the character (ASCII value) to search
for. If the character, its offset is returned, otherwise a value of
-1 is returned. Note that the first character in a string has an
offset of 0, not 1 as in some languages.
o Return Value
An integer value as described above.
o Example
// Count how many times a certain char occurs in a string
int i, count = 0;
str s[] = "abcabcabcabcabc";
i = 0;
do
{
i = strchr(s, i, 'a');
if (i != -1)
count = count + 1;
}
while (i != -1);
Telix v3.00 - SALT Programming Built-in Functions 89
_________________________________________________________________
strcmpi
o Summary
strcmpi(str <string1>, str <string2>);
o Description
The strcmpi function is used to compare two strings (in a similar
manner to the ==, >, and < operators, but ignoring the case of the
strings). The strings are compared character by character until a
difference is found or the end of either string is found, and an in-
teger value is returned as follows:
0 <string1> is equal to <string2>
< 0 <string1> is less than <string2>
> 0 <string1> is greater than <string2>
o Return Value
An integer value as described above.
o Example
if (strcmpi("HeLLo", "hEllO");
prints("This will always be printed");
_________________________________________________________________
strlen
o Summary
strlen(str <s>);
o Description
The strlen function returns the number of characters in the string
<s>. Since strings are terminated with a 0 (NULL) character, this
function really counts the number of characters before a 0 is en-
countered.
o Return Value
An integer value representing the length of a string.
o See Also
strmaxlen
Telix v3.00 - SALT Programming Built-in Functions 90
o Example
str teststr[] = "This is a test string";
printsc("The length of 'teststr' is ");
printn(strlen(teststr));
_________________________________________________________________
strlower
o Summary
strlower(str <s>);
o Description
The strlower function processes the string <s> and changes each up-
per case character to lower case. Other characters are left un-
changed.
o Return Value
None.
o See Also
strupper
_________________________________________________________________
strmaxlen
o Summary
strmaxlen(str <s>);
o Description
The strmaxlen function returns the maximum number of characters that
string <s> can hold. This is the same value as used when the string
is defined elsewhere in the program (e.g. if the string was defined
as 'str hello[16];', a value of 16 would be returned). All strings
are really one character larger than defined, as the last character
is always a terminating 0 (NULL). However, since this value can not
be changed, it is not counted as part of the length of a string.
o Return Value
An integer value as described above.
o See Also
strlen
Telix v3.00 - SALT Programming Built-in Functions 91
_________________________________________________________________
strpos, strposi
o Summary
strpos;(str <string1>, str <substr>, int <start>);
strposi;(str <string1>, str <substr>, int <start>);
o Description
The strpos function is used to search for one string within another.
<string1> is scanned for <substr>, starting at the offset (position)
indicated by <start>. If the sub-string is found, its offset is re-
turned, otherwise a value of -1 is returned. Note that the first
character has an offset of 0, not 1 as in some languages.
strposi is a case insensitive version of the above.
o Return Value
An integer value as described above.
o Example
str teststr[] = "cat dog cat dog";
int i = 0, num = 0;
while (1) // loop as long as needed
{
i = strpos(teststr, "cat", i);
if (i == -1)
break;
i = i + 1; // make sure we don't find the same one
num = num + 1; // increment count
}
prints("'cat' was found ");
printn(num);
prints(" times.");
_________________________________________________________________
strupper
o Summary
strupper(str <s>);
o Description
The strupper function processes the string <s> and changes each
lower case character to upper case. Other characters are left un-
changed.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 92
None.
o See Also
strlower
_________________________________________________________________
subchr
o Summary
subchr(str <s>, int <pos>);
o Description
The subchr function returns the character found at position <pos> in
string <s>. Note that an integer (representing the ASCII value of
the character) is returned, not a string. <pos> may be anywhere
within the string length as defined. Note that positions start from
0. The 1st character in a string is at position 0, the 40th at posi-
tion 39, etc. A string defined with a length of 10 would have valid
positions of 0 to 9, with position 10 always returning the 0 value
that terminates all strings.
o Return Value
An integer value as described above.
o See Also
setchr, subchrs
o Example
// This will print out the contents of a test string, extracting
// each character individually, and stopping when a 0 is reached
// which marks the end of all proper strings
int i;
str s[] = "This is a test string";
for (i = 0; subchr(s, i) != 0; ++i)
printc(subchr(s, i));
Telix v3.00 - SALT Programming Built-in Functions 93
_________________________________________________________________
subchrs
o Summary
subchrs(str <source>, int <pos>, int <count>, str <target>);
o Description
The subchrs function copies a number of characters from one string
into another, Characters from position <pos> in <source> are copied
until into string <target> (note that SALT string offsets start at
0, not 1 as in some languages). <count> characters are copied. Only
as many characters as will fit in <target> are copied.
This function is very similar to substr, except that it is not
string oriented, and does not stop copying characters when a 0 value
is encountered.
o Return Value
None.
o See Also
substr, subchr, copystr, copychrs
_________________________________________________________________
substr
o Summary
substr(str <source>, int <pos>, int <max>, str <target>);
o Description
The substr function copies a portion of one string to another. Char-
acters from position <pos> in string <source> are copied until into
string <target> (note that SALT string offsets start at 0, not 1 as
in some languages). Characters are copied until a 0 (NULL) value is
encountered (normally at the end of every string), or <max> char-
acters are copied. A 0 (NULL) is always copied at the end of the
target string. The 0 does not count as part of the <max>. Only as
many characters as will fit in <target> are copied.
o Return Value
None.
o See Also
subchrs, copystr, copychrs
Telix v3.00 - SALT Programming Built-in Functions 94
o Example
str s[] = "horse cat dog", s2;
substr(s, 6, 3, s2);
if (s2 == "cat")
prints("This will always be printed");
Telix v3.00 - SALT Programming Built-in Functions 95
_________________________________________________________________
tday - tyear
o Summary
tday(int <timeval>);
thour(int <timeval>);
tmin(int <timeval>);
tmonth(int <timeval>);
tsec(int <timeval>);
tyear(int <timeval>);
o Description
These functions all extract time information from <timeval>, which
is a date and/or time of day. If <timeval> represents a date, it is
the number of seconds from Jan 1, 1970 to that date. If <timeval>
represents a time of day, it is the number of seconds from midnight
to that time. If it is both, the two above values are simply added
together. Among others, the curtime and filetime functions return
time/date information in this format.
tday returns an integer value from 1 to 31 representing the day por-
tion of the date stored in <timeval>.
thour returns an integer value from 0 to 23 representing the hour
portion of the time stored in <timeval>.
tmin returns an integer value from 0 to 59 representing the minutes
portion of the time stored in <timeval>.
tmonth returns an integer value from 1 to 12 representing the month
portion of the date stored in <timeval>.
tsec returns an integer value from 1 to 59 representing the seconds
portion of the time stored in <timeval>.
tyear returns an integer value from 1970 to 2019 representing the
year portion of the date stored in <timeval>.
o Return Value
An integer value as described above.
o See Also
curtime, filetime
o Example
int t;
Telix v3.00 - SALT Programming Built-in Functions 96
t = curtime();
printsc("This is month number ");
printn(tmonth(t));
printsc(" in the year ");
printn(tyear(t));
prints(".");
_________________________________________________________________
terminal
o Summary
terminal();
o Description
The terminal function when called allows Telix to process characters
coming in from the serial port and print them on the terminal
screen, and process user keystrokes. If a function has nothing to do
(for example while using the track function), it can call terminal
to make sure characters and user keystrokes are processed. Note that
if a user script wants to process every incoming character (e.g.,
with the cgetc function, the terminal function should never be
called).
o Return Value
None.
o See Also
track
Telix v3.00 - SALT Programming Built-in Functions 97
o Example
// This will wait forever for either of two strings
// to come in from the comm port, and then stop.
int t1, t2, stat;
t1 = track("hello", 0);
t2 = track("good-bye", 0);
while (1) // loop forever
{
terminal(); // The call to terminal() lets any characters
// that come in be looked at by Telix's
// internal routines for a match with.
// Incoming chars are also printed on the
// terminal screen and user keystrokes are
// handled
stat = track_hit(0);
if (stat == t1 || stat == t2) // exit if one of the strings
break; // came in
}
track_free(t1); // stop Telix for looking for more matches
track_free(t2);
_________________________________________________________________
time
o Summary
time(int <timeval>, str <buffer>);
o Description
The time function writes out a time in <buffer> in the form
hh:mm:ss, with hh being the hour in either 12 or 24 hour format
based on the date_format). <timeval> is the time, represented as the
number of seconds since midnight. Time values in this form are re-
turned by the curtime and filetime functions, among others.
o Return Value
None.
o See Also
date, curtime, filetime
Telix v3.00 - SALT Programming Built-in Functions 98
o Example
str s[16];
printsc("The current time is ");
time(curtime(), s);
prints(s);
Telix v3.00 - SALT Programming Built-in Functions 99
_________________________________________________________________
time_up - timer_total
o Summary
time_up(int <thandle>);
timer_free(int <thandle>);
timer_restart(int <thandle>, int <time>);
timer_start(int <time>);
timer_total(int <thandle>);
o Description
The timer functions are used to set and keep track of a timer vari-
able.
The timer_start function is used to start a timer. This timer can
later be used to check if a certain period of time has elapsed from
when the timer was started. This function returns an integer value
called a timer handle, that is used to refer to this timer in the
future. The <time> parameter is the time from the present (in tenths
of a second) after which the timer should be considered elapsed (for
use with the time_up function). If the time_up function will not be
used, then this parameter can be anything.
The time_up function returns a non-zero (TRUE) value if the timer
represented by timer handle <thandle> has elapsed, otherwise a 0
(FALSE) value is returned. The period of time after which a timer
will elapse is specified in the timer_start function.
The timer_total function returns the total time (in tenths of a sec-
ond) since the timer represented by timer handle <thandle> was
started or restarted.
The timer_restart function performs the same things as timer_start,
except that it restarts an existing timer, represented by timer han-
dle <thandle>.
The timer_free function frees a timer variable when it is no longer
needed. <thandle> is the timer handle of the timer to free, and
should originally have been returned by the timer_start function.
After a timer has been freed it should no longer be referred to.
o Return Value
timer_start returns an integer number representing a 'handle' by
which a timer will be referred to.
time_up returns a non-zero (TRUE) or 0 (FALSE) value depending on
whether a timer has elapsed or not.
timer_total returns an integer value representing the elapsed time
Telix v3.00 - SALT Programming Built-in Functions 100
since a timer was started.
timer_restart does not return any significant value.
timer_free does not return any significant value.
o See Also
delay
o Example
int t;
t = timer_start(100); // delay for 10 seconds
while (!time_up(t))
;
timer_free(t);
// start a timer and loop forever, printing the elapsed time
// in tenths of seconds
t = timer_start(0);
while (1)
{
printn(timer_total(t));
prints("");
}
_________________________________________________________________
tolower
o Summary
tolower(int <chr>);
o Description
If the character <chr> is an uppercase character, the tolower func-
tion returns the lowercase equivalent. Otherwise <chr> is returned
unchanged. Note that <chr> is an ASCII value, not a string.
o Return Value
An integer value as described above.
o See Also
toupper
Telix v3.00 - SALT Programming Built-in Functions 101
_________________________________________________________________
tone
o Summary
tone(int <frequency>, int <length>);
o Description
The tone function makes Telix emit a sound of <frequency> for a pe-
riod of time represented by length (in hundredths of a second).
o Return Value
None.
o See Also
alarm
o Example
tone(659, 14);
_________________________________________________________________
toupper
o Summary
tolower(int <chr>);
o Description
If the character <chr> is an lowercase character, the toupper func-
tion returns the uppercase equivalent. Otherwise <chr> is returned
unchanged. Note that <chr> is an ASCII value, not a string.
o Return Value
An integer value as described above.
o See Also
tolower
Telix v3.00 - SALT Programming Built-in Functions 102
_________________________________________________________________
track - track_hit
o Summary
track(str <trackstr>, int <mode>);
track_hit(int <handle>);
track_addchr(int <chr>);
track_free(int <handle>);
o Description
The track and related functions are used to keep track of and wait
for certain strings to come in over the comm port, similar in nature
to the waitfor function. However the latter function can only wait
for one specific string, while with the track functions can handle
more strings at the same time (currently up to 16), and they may ar-
rive in any order (or not arrive at all).
The track function tells Telix to keep track of (watch for) the
string indicated by <trackstr> to come in over the comm port. If
<mode> is 0, case is significant, if <mode> is 1, case is not sig-
nificant. The former is faster and should be used when the many
strings are being watched for. Track returns an integer value called
a 'track handle' which is later used with the track_hit function to
check if this string came in.
When track is called, Telix doesn't loop endlessly waiting for the
string to come in, but instead returns back to the script. As char-
acters come in, Telix checks to see if any of the strings to be
tracked have been matched, and marks those that have. A script can
at any time call the track_hit function to see if the string repre-
sented by <handle> was received. If track_hit returns a non-zero
(TRUE) value, then that string was received, otherwise it wasn't. If
<handle> is 0, then track_hit will return the lowest numbered handle
of any strings that came in, or 0 if none did. The marker on a han-
dle is cleared once track_hit has indicated that the appropriate
string was received.
While a script is executing, Telix is not in terminal mode, and
therefore does not have access to incoming characters, to scan for
matching strings. Therefore, the terminal function must periodically
be called to allow Telix to get a look at incoming characters. This
function is described in the appropriate place in this manual. Al-
ternately, if a script must process these characters itself (with a
function like cgetc), and therefore can not call the terminal func-
tion, they must still be passed by the track routines for string
matching to work. The track_addchr function is used for this. When
it is called, Telix treats the character represented by <chr> as if
it had been received from the terminal handler, and uses it to scan
for matching strings.
The track_free function is used to tell Telix to stop tracking a
Telix v3.00 - SALT Programming Built-in Functions 103
certain string. <handle> is a track handle returned by a previous
call to the track function. It is very important that when a certain
string no longer needs to be tracked, track_free is called, as
tracking a large number of strings can slow down Telix execution. If
<handle> is 0, Telix will stop tracking all string.
o Return Value
All functions return integer values as described above.
o See Also
waitfor
o Example
// Log-on to a BBS, answering two prompts in any order.
// This will wait forever, so for actual use would have
// to be changed a bit. See sample scripts for examples.
int stat, t1, t2;
t1 = track("Name? ", 0);
t2 = track("Password? ", 0);
while (1) // loop as long as needed
{
terminal(); // call terminal function to allow Telix
// to look at incoming characters for
// matches and let Telix process user
// keystrokes
stat = track_hit(0); // see if any matches
if (stat == t1) // name prompt
cputs("Joe Smith^M"); // send name and continue looping
if (stat == t2) // password prompt
{
cputs("mypass^M"); // send password
break; // and get out of loop
}
}
track_free(t1); // free track handles
track_free(t2);
Telix v3.00 - SALT Programming Built-in Functions 104
_________________________________________________________________
transtab
o Summary
transtab(str <filename>, int <table>);
o Description
The transtab function is used to load or clear the incoming or out-
going character translation table. <table> stands for the translate
table to manipulate, with 0 being the incoming, and 1 being the out-
going.
If <filename> is empty (""), Telix will prompt for the name of a
translate table to load into memory.
If <filename> is a valid name for a Telix translate table (saved
from the translate table menu in Telix), it is loaded into memory.
If <filename> is "*CLEAR*", the current translate table in memory is
cleared, and Telix will no longer translate incoming characters.
o Return Value
A value of -1 is returned if there is a problem loading the indi-
cated translate table, otherwise a non-zero (TRUE) value is re-
turned.
o Example
transtab("TELIX.XLT");
_________________________________________________________________
update_term
o Summary
update_term();
o Description
The update_term function is called to make sure Telix updates cer-
tain things relating to the video and terminal page. Fro example,
changes made to the _back_color and _fore_color system variables
will not take effect until this function is called. As well Telix
may sometimes take up to 15 seconds to update the status bar (and in
some cases while scripts are running, won't update it at all). Call-
ing this function ensures that the status bar is updated.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 105
None.
o Example
int temp; // reverse current terminal colors
temp = back_color;
back_color = fore_color;
fore_color = temp;
update_term();
_________________________________________________________________
vgetchr
o Summary
vgetchr();
o Description
The vgetchr function is used to read the character (including color
information) at the current cursor position on the video screen. The
return value contains the character in the first (low) byte,a nd the
color of the character in the higher (second) byte. Each component
may be extracted using the & and >> operators as shown in the exam-
ple below. Basically, if 'c' is the returned character/color value,
the character alone may be obtained by using the expression
(c & 255)
while the color value is
(c >> 8)
o Return Value
An integer value as described above.
o See Also
vputchr
o Example
int chr;
chr = vgetchr(); // Get char/color at current cursor position
printsc("The character was ");
printc(chr & 255); // get character by masking out color byte
printsc(" with a color value of ");
printn(chr >> 8); // shift color byte
Telix v3.00 - SALT Programming Built-in Functions 106
_________________________________________________________________
vputchr
o Summary
vputchr(int <chr>);
o Description
The vputchr function is used to place a character on the screen at
the current cursor position, specifying color information at the
same time. <chr> is the character to place on the screen. the low
byte contains the ASCII value fo the character, while the second
byte contains the color value. In general, a if 'c' is the charac-
ter, and 'color' is the color to use, the proper value is obtained
with the expression
(c + color << 8)
o Return Value
None.
o See Also
vgetchr
o Example
// Place an inverse 'X' in the left top corner of the screen
gotoxy(0, 0);
vputchr('X' + 112 << 8);
_________________________________________________________________
vrstrarea
o Summary
vrstrarea(int <vhandle>);
o Description
The vrstrarea function is used to restore a previously saved portion
of the screen. <vhandle> is the video information handle returned by
a previous call to vsavearea, which saved the screen area.
Note, it is very important that <vhandle> is a valid handle, re-
turned by a previous call to vsavearea, or unpredictable results
will happen.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 107
None.
o See Also
vsavearea
_________________________________________________________________
vsavearea
o Summary
vsavearea(int <x1>, int <y1>, int <x2>, int <y2>);
o Description
The vsavearea function is used to save a rectangular portion of the
screen (to be later restored). <x1>,<y1> is the upper left corner of
the area to save, while <x2>,<y2> is the lower right corner. Charac-
ters (and their colors) currently on the screen in this rectangle
are saved in a buffer, and a 'handle' is returned, which must be
stored and used int he subsequent call to vrstrarea to restore the
saved area. If not enough memory exists to save the video bytes, a
value of -1 is returned instead.
Note that Telix has only a limited amount of space for allocating to
video buffers of this type. At one time, only about as much area as
would amount to a full screen should be saved with calls to this
function.
It is also very important that for every call to this function,
there is a subsequent call to vrstrarea. If this is not done, memory
will become used up until no more is left.
o Return Value
An integer value representing a 'handle' to the saved area.
o See Also
vrstrarea
o Example
int vhandle;
vhandle = vsavearea(0, 0, 79, 24); // save the current screen
myfunc(); // call a function
// which modifies screen
vrstrarea(vhandle); // restore previous screen
Telix v3.00 - SALT Programming Built-in Functions 108
_________________________________________________________________
waitfor
o Summary
waitfor(str <waitstr>, int <timeout>);
o Description
The waitfor function is used to wait for the given string to come in
over the serial port. Timeout is the maximum amount of time, in sec-
onds, to wait for the string. Case is not significant, and the
string must be no longer than 40 characters.
o Return Value
A non-zero (TRUE) value is returned if the string is received from
the serial port in the given time, otherwise a zero (FALSE) value is
returned.
o See Also
track
o Example
if (waitfor("name?", 1800))
prints("The string 'name?' came in from the comm port.");
else
{
prints("The string 'name?' did not come in from the");
prints("comm port in 3 minutes!");
}
Telix v3.00 - SALT Programming Built-in Functions 109
_________________________________________________________________
usagelog
o Summary
usagelog(str <filename>);
o Description
The usagelog function is used to manipulate the Telix usage log fa-
cility.
If <filename> is an empty string (""), Telix will ask for the file-
name to open the usage log to, as if the user had pressed Alt-U in
terminal mode.
If <filename> contains a valid filename, the usage log is opened to
that file. The standard usage log is usually called "TELIX.USE".
If <filename> is "*CLOSE*", and the usage log is currently open, it
is closed.
o Return Value
A value of -1 is returned if there is a problem performing the indi-
cated operation, otherwise a non-zero (TRUE) value is returned.
o See Also
ustamp
o Example
usagelog("TELIX.USE");
_________________________________________________________________
usage_stat
o Summary
usage_stat();
o Description
The usage_stat function returns an integer value representing the
current status of the Usage Log. If the Usage Log is currently open,
a non-zero (TRUE) value is returned, otherwise a value of zero
(FALSE) is returned.
o Return Value
Telix v3.00 - SALT Programming Built-in Functions 110
An integer values as described above.
o See Also
capture_stat
_________________________________________________________________
ustamp
o Summary
ustamp(str <text>, int <new_entry>, int <add_nl>);
o Description
The ustamp function is used to place (stamp) text into the Telix us-
age log. If the usage log is currently not open, this function call
is simply ignored. <text> is the entry that should be placed into
the usage log. If <new_entry> contains a non-zero (TRUE) value, the
current date/time is placed ahead of the text, otherwise it is as-
sumed that this is a continuation of a previous entry and no
date/time is added. If <add_nl> (add new line) is a non-zero (TRUE)
value, a Carriage Return and Line Feed character are added after the
entry. This is usually the case unless something else must be added
on the same line.
o Return Value
A value of -1 is returned if there is a problem writing to the usage
log, otherwise a non-zero (TRUE) value is returned.
o See Also
usagelog
o Example
ustamp("Calling user subroutine... ", 1, 0);
if (user_sub == -1)
ustamp("Failed!, 0, 1);
else
ustamp("Successful", 0, 1);
Telix v3.00 - SALT Programming System Variables 111
5. SYSTEM VARIABLES
Telix has quite a large number predefined built-in variables. They
are called System Variables and are used to store many preferences.
There are both string and numeric system variables, and they are ac-
cessed just as you would access any other variable. To help distin-
guish them apart from normal variables, and to avoid confusion, they
all start with an underscore (_) character.
The following pages contain descriptions of all the system vari-
ables. For each variable, a summary and a description are given. An
example of actual usage of the variable will often be given.
The variables are listed in alphabetical order. So that you may find
related variables (and built-in functions), most variable descrip-
tions have a 'See also' section, which lists related variables and
functions.
Telix v3.00 - SALT Programming System Variables 112
_________________________________________________________________
_add_lf
o Summary
int _add_lf;
o Description
If the _add_lf system variable is set to non-zero (TRUE), a Line
Feed character is automatically added after every Carriage Return
character that comes in.
_________________________________________________________________
_alarm_on
o Summary
int _alarm_on;
o Description
If the _alarm_on system variable is set to non-zero (TRUE), alarms
are enabled in Telix. Note that if the _sound_off system variable is
set to zero (FALSE), alarms will not be heard no matter what the
state of this variable.
o See Also
_sound_on
_________________________________________________________________
_answerback_str
o Summary
str _answerback_str[19];
o Description
The _answerback_str system variable holds the string which Telix
will send when a Ctrl-E (ENQ) character is received while in termi-
nal mode. If this string is empty, nothing is sent. Note that if
Compuserve B transfers are enabled, the answerback string will not
be sent, since CIS B uses the Ctrl-E as part of the transfer pro-
cess. Maximum length is 19 characters.
Telix v3.00 - SALT Programming System Variables 113
_________________________________________________________________
_asc_rcrtrans - _asc_striph
o Summary
int _asc_rcrtrans;
int _asc_remabort;
int _asc_rlftrans;
int _asc_scpacing;
int _asc_scrtrans;
int _asc_secho;
int _asc_sexpand;
int _asc_slftrans;
int _asc_slpacing;
int _asc_spacechr;
int _asc_striph;
o Description
_asc_rcrtrans determines what Telix does with Carriage Return char-
acters during ASCII receives. 0 = do nothing; 1 = strip; 2 = add
Line Feed afterwards.
_asc_remabort is the character which when received from the remote
side during an ASCII transfer is a signal to abort the transfer.
_asc_rlftrans determines what Telix does with Line Feed characters
during ASCII receives. 0 = do nothing; 1 = strip; 2 = add Carriage
Return before.
_asc_scpacing is the time in milliseconds which Telix should wait
before transmitting each character during ASCII sends.
_asc_scrtrans determines what Telix does with Carriage Return char-
acters during ASCII sends. 0 = do nothing; 1 = strip; 2 = add Line
Feed afterwards.
If _asc_secho is set to non-zero (TRUE), Telix will echo each char-
acter during ASCII sends.
If _asc_sexpand is set to non-zero (TRUE), Telix will expand blank
lines to a space character, during ASCII sends.
_asc_slftran determines what Telix does with Line Feed characters
during ASCII sends. 0 = do nothing; 1 = strip; 2 = add Carriage Re-
Telix v3.00 - SALT Programming System Variables 114
turn before.
_asc_slpacing is the time in tenths of seconds which Telix should
wait before transmitting each line during ASCII sends.
_asc_spacechr is the character which Telix should wait for during
ASCII sends, before transmitting each line (0 means no wait).
If _asc_striph is set to non-zero (TRUE), Telix will strip the high
(most significant) bit of each character in an ASCII transfer.
_________________________________________________________________
_auto_ans_str
o Summary
str _auto_ans_str[48];
o Description
The _auto_ans_str system variable holds the string that should be
sent to the modem to make it automatically answer the phone when it
rings. This string is used by the Host Mode script, among others.
The string will possibly include translation characters as described
in the Telix manual in the section by that name, and should be sent
to the modem with the cputs_tr function. Maximum length is 49 char-
acters.
o See Also
_mdm_init_string
_________________________________________________________________
_back_color
o Summary
int _back_color;
o Description
The _back_color system variable contains the background color which
should be used for text in terminal mode. Allowable values are from
0 - 15. Note that changes to this variable may not be reflected un-
til the screen is cleared.
o See Also
_fore_color
Telix v3.00 - SALT Programming System Variables 115
_________________________________________________________________
_capture_fname
o Summary
str _capture_fname[64];
o Description
The _capture_fname system variable holds the default capture file
filename. The maximum length is 64 characters.
o See Also
_usage_fname
_________________________________________________________________
_cisb_auto
o Summary
int _cisb_auto;
o Description
The _cisb_auto system variable controls whether Compuserve Quick B
auto file transfer are allowed. If this variable is set to a 0
(FALSE) value, requests by the remote (Compuserve) to transfer files
using the Quick B protocol will be ignored.
o See Also
_zmod_auto
_________________________________________________________________
_connect_str
o Summary
str _connect_str[19];
o Description
The _connect_str system variable holds the string which Telix should
scan for when dialing, and should take to mean that a connection has
been established. For Hayes type modems it is usually set to
"CONNECT". Maximum length is 19 characters.
o See Also
_no_connect1 - _no_connect4
Telix v3.00 - SALT Programming System Variables 116
_________________________________________________________________
_date_format
o Summary
int _date_format;
o Description
The contents of the _date_format system variable determines what
format Telix uses for date strings it produces, as follows:
0 mm/dd/yy
1 dd/mm/yy
2 yy/mm/dd
o See Also
_time_format
_________________________________________________________________
_dial_pause
o Summary
int _dial_pause;
o Description
The _dial_pause system variable holds (in seconds) the amount of
time to wait between the end of one dialing attempt and the be-
ginning of another. Most modems don't need more than a 1 second
pause.
_________________________________________________________________
_dial_time
o Summary
int _dial_time;
o Description
The _dial_time system variable holds the amount of time Telix should
wait for a connection when dialing, in seconds (e.g. 30).
o See Also
_dial_pause
Telix v3.00 - SALT Programming System Variables 117
_________________________________________________________________
_dialpost
o Summary
str _dialpost[19];
o Description
The _dialpost system variable holds the string (the dialing postfix)
which should be sent to the modem after the number, when dialing.
For Hayes type modems, it is usually just a Carriage Return. Maximum
length is 19 characters. This string will possibly include some
translation characters, as described in the Telix manual, and should
be sent to the modem with the cputs_tr function.
o See Also
_dialpref, _dialpref2, _dialpref3, _redial_stop
_________________________________________________________________
_dialpref
o Summary
str _dialpref[19];
str _dialpref1[19];
str _dialpref2[19];
o Description
The _dialpref system variable holds the string which should be sent
to the modem before the number, when dialing. For Hayes type modems,
it is usually set to "ATDT". Maximum length is 19 characters. This
string will possibly include translation characters, as described in
the Telix manual, and should be sent to the modem with the cputs_tr
function.
The _dialpref2 and _dialpref3 are the other two dialing prefixes
that may be defined in Telix.
o See Also
_dialpost, _rdl_stop
Telix v3.00 - SALT Programming System Variables 118
_________________________________________________________________
_dir_prog
o Summary
str _dir_prog[64];
o Description
The _dir_prog system variable holds the name of the disk directory
program that should be run when the user selects the 'Files direc-
tory' option of the DOS Functions menu. If this variable is left
empty (""), the DOS 'dir' command is used. Maximum length is 15
characters.
_________________________________________________________________
_disp_free
o Summary
int _disp_free
o Description
If the _disp_free system variable is set to non-zero (TRUE), Telix
will display the amount of free space available on the drive when
the user presses Alt-R to download a file.
_________________________________________________________________
_down_dir
o Summary
str _down_dir[64];
o Description
The _down_dir system variable holds the default download directory
name. When a file is downloaded (received), if the user specifies a
drive and/or directory in the name, the file is put there. However,
if only a name is specified, the file is placed in the directory in-
dicated by _down_dir. The maximum length is 64 characters, and this
string should end with the backslash character, '\'.
o See Also
_up_dir, receive
Telix v3.00 - SALT Programming System Variables 119
_________________________________________________________________
_editor
o Summary
str _editor[64];
o Description
The _editor system variable holds the name of the editor that should
be run when the user presses Alt-A. The editor should either be on
the DOS Path, in which case only the name needs to be given, or else
the entire pathname (drive, directory, name) must be given. The max-
imum length is 64 characters. If a batch file is to be run the .BAT
extension must be given.
_________________________________________________________________
_entry_enum
o Summary
int _entry_enum;
o Description
The _entry_enum variable is set by the dialing routines. When a con-
nection is established while dialing, the entry number of the dial-
ing directory entry connected to is stored here. If a manual number
is connected to, the value 0 is stored here.
o See Also
_entry_name
dial, redial
Telix v3.00 - SALT Programming System Variables 120
_________________________________________________________________
_entry_name - _entry_pass
o Summary
str _entry_name[29];
str _entry_num[17];
str _entry_pass[14];
o Description
The _entry_name system variable is set by the dialing routines. When
a connection has been established the name portion of the dialing
directory entry connected to is copied here, for use by script
files. The maximum length is 29 characters.
The _entry_num system variable is set in the same way, and holds the
phone number of the entry connected to. The maximum length is 17
characters.
The entry_pass system variable is set in the same way, and holds the
password from the entry connected to. This may be used to perform
logons. The maximum length is 14 characters.
o See Also
_entry_enum
dial, redial
_________________________________________________________________
_ext_filespec
o Summary
str _ext_filespec[64];
o Description
This variable is for use by scripts implementing external protocols.
When an external protocol has been defined as called by a script,
this variable is first loaded with the filespec (file specification)
typed by the user at the transfer menu. The appropriate script is
then run. The script can for example pass this name to a program
which implements the actual protocol. Note that some file transfer
protocols do not require the user to supply the name on downloads,
in which case this variable is left empty.
Telix v3.00 - SALT Programming System Variables 121
_________________________________________________________________
_fore_color
o Summary
int _fore_color;
o Description
The _fore_color system variable contains the foreground color which
should be used for text in terminal mode. Allowable values are from
0 - 15. Note that changes to this variable may not be reflected un-
til the screen is cleared.
o See Also
_back_color
_________________________________________________________________
_image_file
o Summary
str _image_file[64];
o Description
The _image_file system variable holds the full name of the file that
screen images are saved to when the user presses Alt-I while in ter-
minal mode. If this file already exists, data is appended to it.
_________________________________________________________________
_local_echo
o Summary
int _local_echo;
o Description
The _local_echo system variable controls whether or not characters
typed in terminal mode are echoed on the screen. If _local_echo is
set to non-zero (TRUE), characters are echoed, otherwise they are
not.
Telix v3.00 - SALT Programming System Variables 122
_________________________________________________________________
_mdm_hang
o Summary
str _mdm_hang[19];
o Description
The _mdm_hang system variable holds the string that should be sent
to the modem to hang it up when the user presses Alt-H. Note that
this string will only be sent to the modem if Telix can't first
hang-up the modem by turning off a signal on the serial port called
the DTR line. This string may contain translation characters as de-
fined in the Telix manual, and should be sent to the modem with the
cputs_tr function. Maximum length is 19 characters.
o See Also
_mdm_init, _auto_ans_str
_________________________________________________________________
_mdm_init_str
o Summary
str _mdm_init_str[49];
o Description
The _modem_init system variable holds the string that should be sent
to the modem when Telix starts-up. It is usually used to make sure
certain settings in the modem are right. This string may contain
translation characters as defined in the Telix manual, and should be
sent to the modem with the cputs_tr function. Maximum length is 49
characters.
o See Also
_auto_ans_str, _mdm_hang
Telix v3.00 - SALT Programming System Variables 123
_________________________________________________________________
_no_connect1 - _no_connect4
o Summary
str _no_connect1[19];
str _no_connect2[19];
str _no_connect3[19];
str _no_connect4[19];
o Description
These system variables contain the strings that Telix should scan
for when dialing, and take to mean that a connection has not been
established (i.e., the number was busy or there was no answer). The
maximum length for each string is 19 characters.
o See Also
_connect_str
_________________________________________________________________
_qdbar_on
o Summary
int _qdbar_on;
o Description
If the _qdbar_on system variable is set to non-zero (TRUE), the
quick dialing bar is shown first when Alt-D is pressed; otherwise
the user is taken directly to the dialing directory screen.
Telix v3.00 - SALT Programming System Variables 124
_________________________________________________________________
_redial_stop
o Summary
str _redial_stop[19];
o Description
The _redial_stop system variable holds the string that should be
sent to the modem to stop a dialing attempt. It usually just holds a
Carriage Return character. This string may contain translation
characters as described in the Telix manual, and should be sent to
the modem with the cputs_tr function. Maximum length is 19 charac-
ters.
o See Also
_dialpref, _dialpref2, _dialpref3, _dialpost
_________________________________________________________________
_scr_chk_key
o Summary
int _scr_chk_key;
o Description
Between every command while executing a script file, Telix checks
the keyboard buffer to see if the user has requested an abort. This
however gets in the way of the inkey function among others. As well,
it is sometimes necessary to stop the user from being able to abort
the script. If _scr_chk_key is set to zero (FALSE), Telix will no
longer check for user aborts requests during script execution. Set-
ting it back to non-zero (TRUE) will turn the checks back on. When
modifying this variable in a script file, it is a good idea to save
the old state in a scratch variable and restore it when done.
o See Also
inkey
Telix v3.00 - SALT Programming System Variables 125
_________________________________________________________________
_script_dir
o Summary
str _script_dir[64];
o Description
The _script_dir system variable holds the full path of the directory
where Telix should look for compiled script files when a script is
selected to be run. When a script is selected to be run, Telix uses
this procedure: if the name includes the drive and/or directory,
only that path is searched. If the name includes only the filename,
the current directory is first searched for the script file, and
then the directory pointed to by the _script_dir variable. This
string should end in the slash character, '\'. The maximum allowed
length is 64 characters.
o See Also
_telix_dir, _up_dir, _down_dir
_________________________________________________________________
_sound_on
o Summary
int _sound_on;
o Description
If the _sound_on system variable is set to non-zero (TRUE) sound is
enabled in Telix, otherwise all sound is shut off.
o See Also
_alarm_on
_________________________________________________________________
strip_high
o Summary
int _strip_high;
o Description
The _strip_high system variable controls what Telix does with the
high (most significant) bit of incoming characters while in terminal
mode. If this variable is set to s non-zero (TRUE) value, Telix will
strip the high bit of incoming characters.
Telix v3.00 - SALT Programming System Variables 126
_________________________________________________________________
_swap_bs
o Summary
int _swap_bs;
o Description
The _swap_bs system variable controls what Telix sends when the
Backspace key is pressed. If this variable is 0, Telix will send a
Backspace character when Backspace is pressed, and a DEL character
when Ctrl-Backspace is pressed. If this variable is set to 1, Telix
will reverse these codes.
o See Also
_dest_bs
_________________________________________________________________
_telix_dir
o Summary
str _telix_dir[64];
o Description
The _telix_dir system variable holds the full path to reach the
Telix program's base directory (e.g. 'C:\TELIX\'). Changing this
variable is not recommended, as if a wrong value is used, Telix will
probably not be able to find many needed files. The maximum length
is 64 characters.
If this variable is changed, it is imperative that a backslash char-
acter, '\', is found at the end. Telix builds paths to many files by
appending certain names to this string. If the slash is missing, it
will cause many problems.
o See Also
_script_dir, _up_dir, _down_dir
Telix v3.00 - SALT Programming System Variables 127
_________________________________________________________________
_time_format
o Summary
int _time_format;
o Description
The _time_format system variable determines what format Telix uses
for time strings it produces. If _time_format is 0, Telix will use a
12 hour format, otherwise a 24 hour format will be used.
o See Also
_date_format
_________________________________________________________________
_up_dir
o Summary
str _up_dir[64];
o Description
The _up_dir system variable holds the default upload directory name.
When a file is to be ed (sent), if the user specifies a drive and/or
directory in the name, the file is taken from there. However, if
only a name is specified, the file is searched for in the directory
indicated by _up_dir. This variable should end with a slash charac-
ter, '\'. The maximum length is 64 characters.
o See Also
_down_dir
_________________________________________________________________
_usage_fname
o Summary
str _usage_fname[64];
o Description
The _usage_fname system variable holds the default Usage Log file-
name. The maximum length is 64 characters.
o See Also
_capture_fname
Telix v3.00 - SALT Programming System Variables 128
_________________________________________________________________
_zmod_auto
o Summary
int _zmod_auto;
o Description
The _zmod_auto system variable controls whether or not Zmodem auto-
downloads are allowed. If Telix is in terminal mode and receives an
auto download request Telix will ignore it if this variable is set
to a 0 (FALSE) value (however, the user can still receive the file
by manually selecting the Zmodem protocol from the Alt-R menu).
o See Also
_cisb_auto
_________________________________________________________________
_zmod_rcrash
o Summary
int _zmod_rcrash;
o Description
The _zmod_rcrash system variable controls whether the Zmodem receive
Crash Recovery (resume) option is on. If this variable is set to a
non-zero (TRUE) value, Telix will try to resume aborted transfers
during a Zmodem download.
o See Also
_zmod_scrash
Telix v3.00 - SALT Programming System Variables 129
_________________________________________________________________
_zmod_scrash
o Summary
int _zmod_scrash;
o Description
The _zmod_scrash system variable controls whether the Zmodem send
Crash Recovery (resume) option is on. If this variable is set to a
non-zero (TRUE) value, Telix will try to tell the other side to re-
sume aborted transfers during a Zmodem upload.
o See Also
_zmod_rcrash
Telix v3.00 Appendix A 130
6. APPENDIX A - ASCII CHARACTER SET
The ASCII character set consists if 128 characters, with each char-
acter having an ASCII value, in the range of 0 to 127. The IBM PC
uses the IBM Extended ASCII set, which adds a further 128 values, to
provide extra symbols. The following table lists the regular ASCII
character set. The first column contains the ASCII control charac-
ters, which can not normally be printed, and are given by name.
Dec Hex Ctrl Name Dec Hex Chr Dec Hex Chr Dec Hex Chr
0 00 ^@ NUL 32 20 64 40 @ 96 60 `
1 01 ^A SOH 33 21 ! 65 41 A 97 61 a
2 02 ^B STX 34 22 " 66 42 B 98 62 b
3 03 ^C ETX 35 23 # 67 43 C 99 63 c
4 04 ^D EOT 36 24 $ 68 44 D 100 64 d
5 05 ^E ENQ 37 25 % 69 45 E 101 65 e
6 06 ^F ACK 38 26 & 70 46 F 102 66 f
7 07 ^G BEL 39 27 ' 71 47 G 103 67 g
8 08 ^H BS 40 28 ( 72 48 H 104 68 h
9 09 ^I HT 41 29 ) 73 49 I 105 69 i
10 0a ^J LF 42 2a * 74 4a J 106 6a j
11 0b ^K VT 43 2b + 75 4b K 107 6b k
12 0c ^L FF 44 2c , 76 4c L 108 6c l
13 0d ^M CR 45 2d - 77 4d M 109 6d m
14 0e ^N SO 46 2e . 78 4e N 110 6e n
15 0f ^O SI 47 2f / 79 4f O 111 6f o
16 10 ^P DLE 48 30 0 80 50 P 112 70 p
17 11 ^Q DC1 49 31 1 81 51 Q 113 71 q
18 12 ^R DC2 50 32 2 82 52 R 114 72 r
19 13 ^S DC3 51 33 3 83 53 S 115 73 s
20 14 ^T DC4 52 34 4 84 54 T 116 74 t
21 15 ^U NAK 53 35 5 85 55 U 117 75 u
22 16 ^V SYN 54 36 6 86 56 V 118 76 v
23 17 ^W ETB 55 37 7 87 57 W 119 77 w
24 18 ^X CAN 56 38 8 88 58 X 120 78 x
25 19 ^Y EM 57 39 9 89 59 Y 121 79 y
26 1a ^Z SUB 58 3a : 90 5a Z 122 7a z
27 1b ^[ ESC 59 3b ; 91 5b [ 123 7b {
28 1c ^\ FS 60 3c < 92 5c \ 124 7c |
29 1d ^] GS 61 3d = 93 5d ] 125 7d }
30 1e ^^ RS 62 3e > 94 5e ^ 126 7e ~
31 1f ^_ US 63 3f ? 95 5f _ 127 7f DEL
Telix v3.00 Appendix B 131
7. APPENDIX B - EXTENDED KEY SCAN CODES
The following chart lists keyboard scan codes for special non-ASCII
keys, as returned by inkey and inkeyw, and used by the keyget, key-
set, keyload, and keysave SALT functions. Normal keys which are
within the ASCII set are listed in the preceding appendix.
Key Normal w / Ctrl w / Alt w / Shift
Dec Hex Dec Hex Dec Hex Dec Hex
---------------------------------------------------------------
F1 15104 3b00 24064 5e00 26624 6800 21504 5400
F2 15360 3c00 24320 5f00 26880 6900 21760 5500
F3 15616 3d00 24576 6000 27136 6a00 22016 5600
F4 15872 3e00 24832 6100 27392 6b00 22272 5700
F5 16128 3f00 25088 6200 27648 6c00 22528 5800
F6 16384 4000 25344 6300 27904 6d00 22784 5900
F7 16640 4100 25600 6400 28160 6e00 23040 5a00
F8 16896 4200 25856 6500 28416 6f00 23296 5b00
F9 17152 4300 26112 6600 28672 7000 23552 5c00
F10 17408 4400 26368 6700 28928 7100 23808 5d00
---------------------------------------------------------------
1 30720 7800
2 30976 7900
3 31232 7a00
4 31488 7b00
5 31744 7c00
6 32000 7d00
7 32256 7e00
8 32512 7f00
9 32768 8000
10 33024 8100
---------------------------------------------------------------
Up 18432 4800
Down 20480 5000
Left 19200 4b00 29440 7300
Right 19712 4d00 29696 7400
Home 18176 4700 30464 7700
End 20224 4f00 29952 7500
PgUp 18688 4900 33792 8400
PgDn 20736 5100 30208 7600
Ins 20992 5200
Del 21248 5300
---------------------------------------------------------------
Telix v3.00 Appendix C 132
8. APPENDIX C - COLOR VALUES
Several SALT functions, such as pstra, use color attribute values. A
character on the text screen has a foreground color, and a back-
ground color. Possible colors are numbered as follows:
Black 00
Blue 01
Green 02
Cyan 03
Red 04
Magenta 05
Brown 06
Light Grey 07
Dark Grey 08
Light Blue 09
Light Green 10
Light Cyan 11
Light Red 12
Light Magenta 13
Yellow 14
White 15
To obtain a color attribute value for a color combination, the for-
mula is
color attribute value =
foreground color value + (16 * background color value)
Therefore, a Yellow character on a Blue background would have a
color attribute value of 30 (14 + (16 * 1)).
Telix v3.00 - SALT Programming Index 133
Capture_stat 27
Carrier 27
Chatmode 28
9. INDEX Cinp_cnt 28
Clear_scr 30
_add_lf 112 Copychrs 30
_alarm_on 112 Copystr 31
_answerback_str 112 Cputc 32
_back_color 114 Cputs 33
_capture_fname 115 Cputs_tr 33
_cisb_auto 115 Cursor_onoff 34
_connect_str 115 Date 35
_date_format 116 Delay 36
_dial_pause 116 Delay_scr 36
_dial_time 116 Dial 37
_dialpost 117 Dos 38
_dialpref 117 Dosfunction 39
_dialpref1 117 Exittelix 39
_dialpref2 117 Fclearerr 40
_dir_prog 118 Fclose 40
_disp_free 118 Feof 41
_down_dir 118 Ferror 42
_editor 119 Fflush 42
_entry_enum 119 Fgetc 43
_entry_name 120 Fgets 44
_entry_num 120 Fileattr 45
_entry_pass 120 Filefind 47
_ext_filespec 120 Filesize 48
_fore_color 121 Filetime 49
_image_file 121 Flushbuf 50
_local_echo 121 Fnstrip 51
_mdm_hang 122 Fopen 52
_mdm_init_str 122 Fputc 53
_no_connect1 123 Fputs 53
_no_connect2 123 Fread 54
_no_connect3 123 Fseek 55
_no_connect4 123 Ftell 56
_qdbar_on 123 Fwrite 56
_redial_stop 124 Get_baud 57
_scr_chk_key 124 Get_datab 57
_script_dir 125 Get_parity 58
_sound_on 125 Get_port 58
_swap_bs 126 Get_stopb 59
_telix_dir 126 Gets 59
_time_format 127 Getsxy 60
_up_dir 127 Gotoxy 61
_usage_fname 127 Hangup 62
_zmod_auto 128 Helpscreen 62
_zmod_rcrash 128 Inschrs 64
_zmod_scrash 129 Is_loaded 66
Alarm 23 Isalnum 65
Box 24 Iscntrl 65
Call 25 Isdigit 65
Calld 25 Islower 65
Capture 26 Isupper 65
Telix v3.00 - SALT Programming Index 134
Itos 66 Toupper 101
Keyget 67 Track 102
Keyload 68 Track_addchr 102
Keysave 68 Track_free 102
Keyset 69 Track_hit 102
Load_scr 70 Transtab 104
Loadfon 70 Tsec 95
Newdir 71 Tyear 95
Printc 71 Update_term 104
Printn 73 Usage_stat 109
Prints 74 Usagelog 109
Printsc 74 Ustamp 110
Printsc_trm 74 Waitfor 108
Pstra 75
Pstraxy 75
Receive 76
Redial 77
Run 78
Scroll 79
Send 80
Send_brk 81
Set_cparams 81
Set_defprot 82
Set_port 83
Set_terminal 84
Setchr 82
Setchrs 83
Show_directory 85
Stoi 86
Strcat 87
Strchr 88
Strcmpi 89
Strip_high 125
Strlen 89
Strlower 90
Strmaxlen 90
Strpos 91
Strposi 91
Strupper 91
Subchr 92
Subchrs 93
Substr 93
Tday 95
Terminal 96
Thour 95
Time 97
Time_up 99
Timer_free 99
Timer_restart 99
Timer_start 99
Timer_total 99
Tmin 95
Tmonth 95
Tolower 100
Tone 101